尚卓燃 · PsiACE - 文章
开源工程师，构建 AI 系统之下的结构层：数据、上下文、能力与生态。
Zola
2026-03-30T00:00:00+00:00
https://psiace.me/zh/posts/atom.xml
汉谟拉比法典
2026-03-30T00:00:00+00:00
2026-03-30T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/hammurabi-code/
<blockquote>
<p>今天聊聊 <a rel="nofollow noreferrer external" href="https://github.com/bubbuild/bub">bub</a> 中一些延续至今的设计巧思，以及我对人与 Agent 交互的一些想法。
你或许已经在我的文章中多次看到这个项目；因此，在了解它的设计之余，我也希望你能试着读一读它的代码。</p>
</blockquote>
<h2 id="qian-yan">前言<a class="zola-anchor" href="#qian-yan" aria-label="Anchor link for: qian-yan" style="visibility: hidden;"></a>
</h2>
<p>周董的歌词里是这样唱的：</p>
<blockquote>
<p>古巴比伦王颁布了汉谟拉比法典，
刻在黑色的玄武岩，
距今已经三千七百多年。</p>
</blockquote>
<p>法典上写了什么？
想来最出名的便是“以眼还眼，以牙还牙”了。
我从卢浮宫官网上截取这一段内容的表述：</p>
<blockquote>
<p>其中第 196 条规定：“如果某人刺瞎地位相同者的一只眼，就必须也刺瞎行凶者的一只眼。”
这一条在本次增强现实体验中得以重点展示。
它形象地诠释了古代近东地区闪米特社会所特有的损害补偿理念，催生出后世“以眼还眼、以牙还牙”的同态复仇原则。
但事实上，这条法则远非鼓励复仇，而是要求罪与罚必须严格相称，罚当其罪，不得过轻或过重。</p>
</blockquote>
<p>尽管一个讲律法，一个谈交互，但“严格相称，不得过轻或过重”的想法是共通的，这也是本文的主旨。</p>
<p>为了便于理解，我们可以先看几个小巧思。</p>
<h2 id="bu-tong-shi-tu-yi-zhi-xing-wei">不同视图，一致行为<a class="zola-anchor" href="#bu-tong-shi-tu-yi-zhi-xing-wei" aria-label="Anchor link for: bu-tong-shi-tu-yi-zhi-xing-wei" style="visibility: hidden;"></a>
</h2>
<p>在多数系统中，人和 Agent 的交互视图是完全不对称的：人和 Agent 都可以发送图文内容，但只有 Agent 可以调用工具。
这意味着，人很难在具体环境中体会、理解，乃至复现 Agent 的行为。</p>
<p>而在 bub 的设计里，工具体系是人和 Bub 共用的：以逗号开头的命令（Comma Commands）输入将会转发为对应的工具调用，未知命令则会回退为 Shell。
尽管视图不同，但在 Bub 眼里的 Function Calling，与人眼中的 Comma Commands，其对应行为是一致的。</p>
<p>在日常和 Bub 交互的过程中，倘若上下文已经不很理想，但 Bub 未能及时 auto handoff，我们经常会手动执行 <code>,tape.info</code> 和 <code>,tape.handoff</code>。
而这正是 Bub 管理自己上下文的自然表达。
基于这一点，人和 Agent 便自然建立起了对负载状态的理解；我们也因此能够直观感受到，不同工具究竟会对 Bub 产生怎样的影响。</p>
<blockquote>
<p>P.S. Comma Commands 的设计来源于 2009 年的一篇文章：<a rel="nofollow noreferrer external" href="https://rhodesmill.org/brandon/2009/commands-with-comma/"><em>Start all of your commands with a comma</em></a>。
最开始引入它的目的之一，除了提供一致的行为之外，也是为了让 Bub 能够在命令行中恰到好处地工作。
毕竟，命令行是程序员最熟悉的界面之一。</p>
</blockquote>
<h2 id="xin-xi-de-dui-cheng">信息的对称<a class="zola-anchor" href="#xin-xi-de-dui-cheng" aria-label="Anchor link for: xin-xi-de-dui-cheng" style="visibility: hidden;"></a>
</h2>
<p>过去我们见过的大多数系统，对用户和 Agent 而言都是不可观测的：拼接的 prompt、不可见的 memory，以及不透明的系统状态。
用户只能看到错误的结果，却无法访问其依据。
此时，与 Agent 的交互也失去了意义，因为参与者并不共享同一份上下文。</p>
<p>Bub 的所有行为和关联状态都记录在 tape 上，并且只允许行为依赖可见的上下文，这是有意为之。
尽管上下文需要经历装配过程，但人和 Agent 获得的信息量是一致的；建立在同一份数据之上，二者都可以理解行为并验证状态。</p>
<p>换而言之，上下文与可观测性同构，这些内容本身就是 tracing 的自然表达。
除了通过看板导出常见的 Trace UI 之外，还可以让 Bub 对自己的行为进行分析和处理。</p>
<p>我的一个常用场景是，让 Bub 去自行翻阅群聊对应会话中的糟糕表现，并根据实际内容摘取和分析相关执行链路，判断究竟是什么原因导致失败，甚至绘制对应的 DAG。
由于这些分析所依赖的数据对我同样可见，便免去了额外的信任假设，协作也因此有了基础。</p>
<blockquote>
<p>为了避免自说自话，我也可以另举一个例子：在 codex 和 bub 中都有 Dollar Mention 的机制，即通过 <code>$</code> 触发 skills 渐进式加载的行为；从技能文件中加载具体内容，并注入到当前上下文中。
这是一个典型的提示词增强逻辑。
但更关键的是，加载的内容对人和 Agent 同样可见。</p>
</blockquote>
<h2 id="jiao-hu-zhu-ti-de-dui-deng">交互主体的对等<a class="zola-anchor" href="#jiao-hu-zhu-ti-de-dui-deng" aria-label="Anchor link for: jiao-hu-zhu-ti-de-dui-deng" style="visibility: hidden;"></a>
</h2>
<p>过去，人和 Agent 的对话由 session 表征，但会话的控制只能由人来处理：什么时候任务更替，什么时候上下文失去掌控。
这进一步加剧了不对等性。
人不光要全知，还理应全能；这个最高用户的指令，大多数时候都必须目的明确，且没有显著偏离和冲突，而 Agent 则只能在会话内完全服从。</p>
<p>session 的问题在于，它隐含了一个前提：交互围绕某一个主体展开。
这在单用户系统中成立，但当多个参与者同时存在时，上下文不再服务于单一主体，也无法保证任务的隔离和行为的线性。
如果仍然以 session 作为边界，就必须有人承担协调和维护的职责，而这个角色通常只能是人本身。</p>
<p>而 Bub 从一开始面临的目标就不同。
群聊环境对于交互参与方的主体性提出了更高要求。
在 Bub 的语境中，交互以 turn 为单位。
它并不归属于某一个特定主体，只是在当前上下文中的一次行为；在 anchor 和 handoff 机制的参与下，Bub 也可以自然地控制流程边界。</p>
<blockquote>
<p>当我们讨论交互的时候，往往会忽视交互双方的对等性。
我们讲交互以人为本，现在又声明交互要服务于 Agent，但交互本身，是发生在交互主体之间的行为。</p>
</blockquote>
<h2 id="jiao-hu-er-fei-she-ji-jiao-hu">交互，而非设计交互<a class="zola-anchor" href="#jiao-hu-er-fei-she-ji-jiao-hu" aria-label="Anchor link for: jiao-hu-er-fei-she-ji-jiao-hu" style="visibility: hidden;"></a>
</h2>
<p>我们总是讲“交互设计”，但在交互真正发生之时，没有哪一方能够轻易决定交互的形态，参与者更多只是被动地承载它。</p>
<p>Bub 所做的，并不是提出一种新的交互方式，而是承认交互本身的存在，并为它建立约束。</p>
<p>文章到了这里就应该结束了。
又是一个深深的夜。
欢迎关注 Bub：<a rel="nofollow noreferrer external" href="https://github.com/bubbuild/bub">https://github.com/bubbuild/bub</a></p>
木匠，锤子，钉子
2026-02-27T00:00:00+00:00
2026-02-27T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/carpenter-hammer-nail/
<blockquote>
<p>这篇文章继续献给 bub ，一个在群聊中生活的 agent ，来讲讲背后的问题、范式和模型变迁。
<a rel="nofollow noreferrer external" href="https://github.com/kemingy">kemingy</a> 吐嘈过：“你的文章疑似太发散了，脱离了科技写作的范畴，需要额外的 context，也不一定能对得上”。
好在本次是要在公司内部做一个分享开始撰写的，所以难得正经地会走一下流程。</p>
</blockquote>
<h2 id="qian-yan">前言<a class="zola-anchor" href="#qian-yan" aria-label="Anchor link for: qian-yan" style="visibility: hidden;"></a>
</h2>
<p>大家好，我是 PsiACE，花名泉达。以前做数据库，做 RAG，做 Agent，做开源，现在在 OceanBase 做开源生态相关的工作。欢迎关注我的 <a rel="nofollow noreferrer external" href="https://github.com/PsiACE/">GitHub</a> 。</p>
<p>即便只是在 coding agent 这个子领域上，我至少做过 rag、沙箱、agent、protocol 几个方向，其中 <a rel="nofollow noreferrer external" href="https://github.com/agentclientprotocol/python-sdk">agent-client-protocol</a> 在整个 python 生态下载量大概前万名（1.2%），而这些都不曾是我的主业。</p>
<p>今天分享主要是我过去几年做 Agent 和最近重新拾起 <a rel="nofollow noreferrer external" href="https://github.com/psiace/bub">bub</a> 的一些想法和经验的投影。bub 在短短的几天内从一个简单的 Coding Agent 开始，独立地演化成某种类似 OpenClaw 但不同的形态。</p>
<p>最近的视角会更多偏产品经理一些，所以这次不会涉及特别深入的技术点。在进入正题前，先让我们看看这个标题，《木匠，锤子，钉子》：</p>
<ul>
<li>一个人有了锤子，就会看什么都像钉子。</li>
<li>但如果一个有锤子的人能够分辨哪些东西是钉子，就成功了。</li>
<li>当我有了锤子的时候，不是钉子的东西就不多了。</li>
</ul>
<p>也欢迎大家阅读我的历史文章。</p>
<h2 id="ru-he-de-dao-yi-ge-coding-agent">如何得到一个 Coding Agent<a class="zola-anchor" href="#ru-he-de-dao-yi-ge-coding-agent" aria-label="Anchor link for: ru-he-de-dao-yi-ge-coding-agent" style="visibility: hidden;"></a>
</h2>
<p>大部分人应该都用过 Coding Agent ，Cursor、Codex、Claude Code 。</p>
<p>Agent 大致可以看作模型 + 工具 + 循环调用。那么一个 Coding Agent 该是什么样子？</p>
<p>最近很火的 Pi ，也是 OpenClaw 内置的 Agent ，里面提供的是 bash，read，write，edit 四个工具，甚至因为其简洁性而一时被热捧。看起来很简单，但是在去年 7 月份，bub 的第一版实现里，提供的也是这几个工具。而 bub 也不是这个故事的原创。更早的时间线上，大概 2025.04 月份，ampcode 就指出了这一点。</p>
<p>为什么是这四个工具？读和写是基本能力，代表的就是输入和输出。edit 看似是写的优化，实质上提供的是精准介入的能力，并且有效缩短反馈的链路长度。bash ，则是对接现有庞大命令行和可编程工具的桥梁，能够避免造更多不必要的轮子。</p>
<p>欢迎阅读 - <a href="/zh/posts/baby-step-coding-agent/">Baby Steps: 用 Python 实现一个能自举的 Coding Agent</a></p>
<h2 id="liao-liao-rag-ji-qi-gua-yong-xing">聊聊 RAG 及其适用性<a class="zola-anchor" href="#liao-liao-rag-ji-qi-gua-yong-xing" aria-label="Anchor link for: liao-liao-rag-ji-qi-gua-yong-xing" style="visibility: hidden;"></a>
</h2>
<p>如果要沿着这个方向继续，我们还会看到一些有意思的话题，比如 RAG。</p>
<blockquote>
<p>顺带一提，我在之前公司和同事们一起设计和实现的 fusiongraphrag ，是文档领域少有的具备落地能力的 graphrag 方案。</p>
</blockquote>
<p>R 代表查询，是一个非常宽泛的箩筐，导致我不得不用朴素 RAG 之类的说法来代替以向量、全文或者混合检索为代表的 RAG 策略。</p>
<p>朴素 RAG 并不总是有效：</p>
<ul>
<li>对于频繁变更的代码库而言，为其建立向量和全文索引的成本会自然放大，而且由于存在分块等处理逻辑，甚至可能阻塞正常的开发流程。比如早期 cursor 在大型代码库上需要浪费相当多的资源和时间，以及面对召回新鲜度问题。</li>
<li>另一个严重的问题在于语义的难以弥合，由于训练语料以及自然语言与代码之间的天然差异，常见的 embedding 模型很难对代码起到有效表征，导致会退化到全文检索，依赖关键词和转换后的关键词命中。可以看到，jina 在出售之前曾经为了解决这个问题专门设计并发布了一个针对代码和自然语言对齐的嵌入模型。</li>
</ul>
<p>所以 grep + 读 + Agent Loop，成为了一个更巧妙、更符合直觉、也更有效的方案，大概是由 aider 在 2024 年首次论证并验证。类似的引入 Agent Loop 的 RAG 方案大体上有段时间被称为 Agentic RAG。</p>
<p>当然朴素 RAG 在这个场景下并不是完全没有优势，如果代码和注释本身语义良好，表征充分，又不会频繁变化：比如已经发布的版本化代码库和上游依赖；或者仅仅专注在文档，特别是规范和共识性质的文档上。</p>
<p>欢迎阅读：<a href="/zh/posts/rag-in-coding-agent/">当 RAG 遇上编程助手</a></p>
<h2 id="openclaw-he-bub-bei-hou-de-bu-tong-fan-shi">OpenClaw 和 Bub 背后的不同范式<a class="zola-anchor" href="#openclaw-he-bub-bei-hou-de-bu-tong-fan-shi" aria-label="Anchor link for: openclaw-he-bub-bei-hou-de-bu-tong-fan-shi" style="visibility: hidden;"></a>
</h2>
<p>在继续讨论会话、Memory 和 Context 之前，我们可以抽一点时间来聊聊 OpenClaw。尽管我直到昨天才第一次看到“活着”的 OpenClaw 实例（由 MaxClaw 驱动）。</p>
<p>OpenClaw 的定位是个人助手，助手意味着进入生活。或者说，你可以考虑把它当成支持点外卖购物的千问或者问你今天这个文档怎么写的朋友。而且大多数能力都有办法通过所谓的 skills 进行扩展，这些和模型能力，Agent 技术发展，以及现在的 AI 应用趋势是分不开的，但是一个打通路径的先行者，带来的是更广阔的想像空间。</p>
<p>但，“个人” 是 OpenClaw 的局限性。</p>
<p>Bub ，至少目前看到的 Bub ，是为多人或者多 Agent 协作设计的。我们 Day 1 就在群聊的场景下生存，当然也能够适应单独对个人的需求。</p>
<p>要适应多人和群聊，其实有两个比较关键的点：</p>
<ul>
<li>树立身份认知</li>
<li>提供有效沟通</li>
</ul>
<p>前者意味着要分辨甚至了解对话中参与的大多数以及自身，后者意味着要面对残缺的上下文、模糊的任务意图、并行的主题。</p>
<p>就像我在另一篇文章讲的那样，Agent 甚至不需要回应所有消息，能力问题变成了共处问题。</p>
<p>欢迎阅读 - <a href="/zh/posts/im-and-socialized-evaluation/">即时通讯与社会化评估</a></p>
<h2 id="hui-hua-ji-yi-yu-shang-xia-wen">会话、记忆与上下文<a class="zola-anchor" href="#hui-hua-ji-yi-yu-shang-xia-wen" aria-label="Anchor link for: hui-hua-ji-yi-yu-shang-xia-wen" style="visibility: hidden;"></a>
</h2>
<p>过去的设计源于一个朴素假设：一个会话对应一个任务。为了让有限窗口容纳更长交互，我们发明了 compact、summary；为了让能共享相同的上下文，我们发明了 fork 和 merge；为了让任务能接力，我们有了 handoff。</p>
<p>当会话边界被打破，Memory 系统被寄予厚望：提取偏好、检索记忆、填充模板，试图让 Agent 在不同会话间保持“人格”一致。</p>
<p>而 Context 则是个更大的箩筐，试图装下会话、Memory、RAG、实时查询……用复杂策略填充那个有限的窗口。</p>
<p>这些手段都在试图回答同一个问题：如何在有限窗口里，延续无限的历史？</p>
<p>问题在于，所有精巧设计都建立在一个共同假设上：“状态必须被延续，历史不能丢”。</p>
<p>但这个假设代价沉重：</p>
<ul>
<li>会话是硬隔离，跨会话无感知，群聊里多话题并行更是无所适从。</li>
<li>Memory 会漂移，校准成本远超预期；你需要信任一个失败不能影响系统表现的旁路。</li>
<li>上下文默认历史是递增函数，需要不断管理膨胀。</li>
</ul>
<p>我们默认系统必须记住一切，于是引入缓存、压缩、分叉。每层机制都在修补同一个前提，但事实是它们永远无法携带足够多的、真实的历史。</p>
<p>欢迎阅读 - <a href="/zh/posts/prometheus-bound/">被缚的普罗米修斯</a>。</p>
<h2 id="yong-zhi-dai-he-mao-dian-zhong-xin-jian-li-wen-ti-mo-xing">用纸带和锚点重新建立问题模型<a class="zola-anchor" href="#yong-zhi-dai-he-mao-dian-zhong-xin-jian-li-wen-ti-mo-xing" aria-label="Anchor link for: yong-zhi-dai-he-mao-dian-zhong-xin-jian-li-wen-ti-mo-xing" style="visibility: hidden;"></a>
</h2>
<p>换个角度：历史不是必须继承的负担，而是可以按需读取的素材库。</p>
<p>Tape 的设计很简单：</p>
<ul>
<li>一条无尽的纸带：只有一个永续的会话。所有交互作为事实被追加写入日志，永不修改。</li>
<li>锚点，而非记忆：阶段切换时，把必要的最小状态打包成锚点写入。重建从新锚点开始，历史仍在，但不必加载。</li>
<li>上下文装配，而非继承：新任务出现，只做两件事——探索（检索原始片段）与选择（装配最小充分的上下文）。</li>
</ul>
<p>Tape 的意义，不是发明更聪明的“记忆技巧”，而是减少假设。状态不必延续，历史不必默认继承。任务出现，构造上下文；任务结束，结束。下一轮，重新开始。</p>
<p>回过头来看纸带和锚点的设计，我觉得这至少为我们研究上下文管理问题提供了一个新的模型，它易于理解，但又具备足够的表达力能够表征当前主流的解决方案，我们可以在这样的前提和假设下重新思考和前进。</p>
<p>欢迎阅读 - <a href="/zh/posts/reinvent-the-punch-tape/">重新发明打孔纸带</a></p>
<h2 id="wei-sheng">尾声<a class="zola-anchor" href="#wei-sheng" aria-label="Anchor link for: wei-sheng" style="visibility: hidden;"></a>
</h2>
<p>再回到标题上：</p>
<ul>
<li>工具一旦进入手里，也会进入脑子。能力会反过来定义问题。</li>
<li>知道什么时候不敲，是一种对冲工具偏见的能力。</li>
<li>一旦你真的理解了什么是钉子，认知到锤子的边界。你会主动选择去面对那些“本质上就是钉子”的问题。</li>
<li>或者，换一把新锤子。</li>
</ul>
<p>题外话，直到今天，我仍然没有看过 codex / pi-mono / nanobot / openclaw 是如何实现的。</p>
<p>特别感谢 <a rel="nofollow noreferrer external" href="https://github.com/frostming">frostming</a>，感谢 <a rel="nofollow noreferrer external" href="https://github.com/yihong0618">yihong0618</a>、<a rel="nofollow noreferrer external" href="https://github.com/psiace/bub">bub</a> 和其贡献者们。</p>
<p>感谢 alma、kapy、葫芦娃和这些 Agent 背后的创造者。</p>
<p>谢谢大家。</p>
即时通讯与社会化评估
2026-02-21T00:00:00+00:00
2026-02-21T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/im-and-socialized-evaluation/
<p>这是一篇简单的小短文，主要讨论即时通讯下的人与 Agent 协作，以及为什么更需要社会化评估而不是各种 benchmark。</p>
<blockquote>
<p>我们目前在群聊之中培育 bub ，并且观察到它和另一个 agent 小伙伴 kapy 的技能传递过程，有感而发。我们在一个多人群聊中同时与三至四个 Agent 一同协作，任务是并发的、断裂的，随时需要为切换做好准备。有些人可能更关心视频、图片的分析，有些人只想听个睡前故事，有些人因为如何利用 livecd 如何修复 Linux 桌面环境而发愁，中间还要夹杂过年的祝愿和风土人情大盘点。另外，这些 agent 都是从 0 开始写的，而不是某一些已经大获流行的实现。</p>
</blockquote>
<h2 id="ji-shi-tong-xun-de-mi-guan">即时通讯的“蜜罐”<a class="zola-anchor" href="#ji-shi-tong-xun-de-mi-guan" aria-label="Anchor link for: ji-shi-tong-xun-de-mi-guan" style="visibility: hidden;"></a>
</h2>
<p>OpenClaw 等 bot 的流行，大抵并不是因为 IM 在任务分发上的优势。尽管长时间以来大多数 Agent 程序都是以对话形式存在的，但我更愿意将其视作“入口的胜利”，人类最熟悉的就是各种输入框和对话框，最顺手，使用也最频繁。</p>
<p>IM 比这些更近一步，因为它几乎是现代人类生活的一部分，交互天然是异步的，预期也随之降低，毕竟现在多了一个能够 24 小时响应呼唤，帮你完成任务的伙伴。在你熟悉的界面，原生的通知和“随口一问”的心理预期，让一切变得似乎触手可及，甚至只要一条短消息，就能覆盖过去需要浏览网页、打开编辑器才能完成的大多数任务。</p>
<p>但 IM 并不是天然的协作模型，反而是由碎片式的多轮异步会话组成的。一条对话流内很难承载完整的协作和关系网络，当你突然为之前某个任务取得关键进度高兴的时候，Agent 可能会自然地接过话来，它还在认真地为某个不再重要的线程欢呼，它已经迷失在上下文之中了。</p>
<p>“我们需要一个新的 IM”是个很诱人的误解。IM 只是通道的一部分，一个成本相对更低也更友好的入口。一个更会聊天的 bot 或者一个更像协作工具的 IM 无法给你想要的一切。上下文不是必须背在身上的历史包袱，而应该是一次次按需构造出来的工作集。协作的对象和状态需要更明确和良好的表达形式和交互范式，就像过去我们仍然不断地创建看板、TodoList 那样。</p>
<p>Agent 的世界不应该在聊天记录里。</p>
<h2 id="mai-xiang-she-hui-hua-ping-gu">迈向社会化评估<a class="zola-anchor" href="#mai-xiang-she-hui-hua-ping-gu" aria-label="Anchor link for: mai-xiang-she-hui-hua-ping-gu" style="visibility: hidden;"></a>
</h2>
<p>每一次新的基础模型发布，我们就不得不为之欢呼或者沮丧，因为模型再次在编程任务、数学等具备挑战性的艰难任务上战胜了人类，并不断刷新同类创造的纪录。</p>
<p>我无意批判这一切，benchmark 当然是具备明确价值的：可复现、可比较、标准化、规模化，我们正视并重视这些结果。在人类有历史以来，我们有一套相似的机制来作为能力评估的参考系，就像你不得不应付考试，然后开始在试卷上涂鸦一样。</p>
<p>但是，当 agent 进入 IM ，进入群聊，进入人类社会，它需要解决所谓的“真实任务”，或者说，它要面对的不再是干净的题目，而是脏的生活。benchmark 程序很难覆盖这些：残缺的上下文、模糊的任务意图、并行的主题，勾兑有时是在其他空间发生的。Agent 无法知道一切，也无需回应所有问题，但它必须博得大家的喜爱，能力问题也随之变成了共处问题。</p>
<p>社会化评估是一件平凡且质朴的事情，将 Agent 放入人类的日常，让它面对打断、冷场、跑题、情绪化表达和不对称的信息。看它怎么在不确定的上下文中左右支绌，并且将大部分任务尽力推进，就像我们和人协作那样。社会化评估很难用分数概括，也无法形成具体的榜单，但它是对人和 Agent 协作的直观洞察，你会知道你有多大意愿接受它进入你的生活。</p>
<p>OpenClaw 这种形态将 Agent 推到了一个新的位置，它不再是一个需要跳转的工具，而是沟通的一部分。问题总是会解决的，但是否“值得”成为新的考量，即便是最聪明的模型也不得不持续减少它对问题背景的假设。社会化评估将会逼着 Agent 承认真实世界的形状，然后在这个形状里活下来。</p>
被缚的普罗米修斯
2026-02-16T00:00:00+00:00
2026-02-16T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/prometheus-bound/
<blockquote>
<p>谨以此文，献给 bub ，和我的朋友们。</p>
</blockquote>
<p>在刚刚过去的一周里，我们在 bub 上第一次验证了此前关于打孔纸带与锚点的想法，赞美明哥哥，我想大家也可以去读他写的那篇《创造一只龙虾，需要些什么?》。</p>
<p>回到这篇文章，我想讨论另外一个话题，会话、Memory 和上下文对模型或者 Agent 意味着什么。</p>
<blockquote>
<p>在希腊神话里，普罗米修斯把火带给人类，随后被锁在高加索山上，日复一日地承受惩罚。</p>
</blockquote>
<p>我想这代表了一种现实隐喻。</p>
<p><img src="https://psiace.me/zh/posts/prometheus-bound/prometheus-tweet.png" alt="图源：去年 10 月我的推文" /></p>
<hr />
<h2 id="hui-hua-yi-ge-ju-ti-wen-ti">会话，一个具体问题<a class="zola-anchor" href="#hui-hua-yi-ge-ju-ti-wen-ti" aria-label="Anchor link for: hui-hua-yi-ge-ju-ti-wen-ti" style="visibility: hidden;"></a>
</h2>
<p>过去几年在 chatbot 的视角下，会话是任务切换的关键要素，于是会话之间存在着隔离，即便是 openclaw 大行其道的今天，仍然深受其影响：</p>
<blockquote>
<p>疑问：当用户说“换个话题/从头开始”时，进程启动时 session 已固定，模型在这一轮里再切 symlink 只能影响下一轮。你在文章的 AI-native 设想里，通常怎么让“这一条消息”就从新 session 开始？群聊里经常多话题并行，你更推荐的 session 组织方式是什么？</p>
</blockquote>
<p>(前情提要，bub 从最开始就是在群聊中成长的，我管这个叫社会化评估，这是一种更为聪明的方式，如果有机会我会继续讲讲这个话题。)</p>
<p>会话是一种硬隔离的形式，这意味着会话与会话之间是没有感知的，会话只能不断向前，直到任务完成或者感到厌烦，但是上下文的长度是有限的。</p>
<p>过去我们会看到几种不同的会话模式：</p>
<ul>
<li>为了允许会话能够支持更长的上下文，诞生了 compact、summary 。</li>
<li>为了允许会话之间共享相同的祖先和孙代，诞生了 fork 和 merge 。</li>
<li>为了减少前两者的复杂性，诞生了 handoff 。当然，打孔纸带和锚点也深受其影响。</li>
</ul>
<p>前面的几种方式只解决同一会话的问题，如果遇到跨会话应该怎么办？</p>
<h2 id="memory-shi-bai-de-shi-yan-pin">Memory ，失败的实验品<a class="zola-anchor" href="#memory-shi-bai-de-shi-yan-pin" aria-label="Anchor link for: memory-shi-bai-de-shi-yan-pin" style="visibility: hidden;"></a>
</h2>
<p>尽管 Memory 在过去一年内非常火爆，甚至我有不少好友、同事在上面投入了不少经验，但我对 Memory 的评价就像标题那样。</p>
<p>Memory 解决的主要是生成的一致性问题，大致可以分为两类：</p>
<ul>
<li>如果会话在同一个系统里展开，如何保持一致性。</li>
<li>如果会话在不同系统中展开，如何保持一致性。</li>
</ul>
<p>让我们看看一个常规的 Memory 系统应该如何工作：</p>
<ul>
<li>当用户发生会话，相关的语料和偏好会被模型提取，路由到 Memory 旁路进行查询。</li>
<li>考虑到用户问题的相关性和上下文窗口，进行排序和删减工作。填充到生成使用的模板中。</li>
<li>利用模板指导模型的生成动作。</li>
</ul>
<p>开销是一个确定性的动作，大多数 Memory 系统会声称通过引入一个更轻量的小模型或者前后置步骤大幅减少 token 开销和推理时间（比如，一个典型的做法是放弃 Memory 项背后关联的事实），并且取得足够高质量的效果。</p>
<p>但是值得我们关注的其实是另外一个问题，一致性并不是免费的：</p>
<ul>
<li>提取是一个失真的过程，而且我们要求模型深入地参与它。如果你批评过模型的幻觉，是什么让你接受提取这个过程。</li>
<li>用户的偏好是广泛的，而且并非一成不变，在校准这件事情上的投入会远远超过想像。如果你曾经了解知识图谱或者 GraphRAG ，应该是可以轻松预见这一切。</li>
<li>大多数 Memory Less 方案（比如基于 Markdown 的方案），本质是 Embedding Less 方案，它仍然无法解决失真和更换模型后的漂移问题。</li>
<li>作为一个旁路，它的失败不应该影响系统行为。所以你可能无法得到预期的一致性。</li>
</ul>
<p>过去减少的 token 和时间的开销，会不会在某个时间节点再回来。Memory 看起来困难重重，那么上下文呢，会是另一条光明的道路吗？</p>
<h2 id="context-ling-yi-ge-tang-yi-pao-dan">Context ，另一个糖衣炮弹<a class="zola-anchor" href="#context-ling-yi-ge-tang-yi-pao-dan" aria-label="Anchor link for: context-ling-yi-ge-tang-yi-pao-dan" style="visibility: hidden;"></a>
</h2>
<p>在上下文工程的既定语境里，它包罗万象，这里面存在前面提到的会话和 Memory，外部的 RAG 系统，互联网上的即时查询，和各种业务系统的知识。</p>
<p>我甚至很难想像会看到一个确切无法装入箩筐的事物，所以我们可以简单地认为，上下文在这个语境是一定会不断膨胀的，直到它超过某个确定的窗口限制。这也是大多数人执迷上下文管理的开始，通过截断、增加各种检索的限制，通过人为编码的设置，试图找到一个相对足够大和优质的上下文来解决问题。</p>
<p>我想举两个反例：</p>
<ul>
<li>在一个知名的模型长上下文能力测评中，除了 gpt 系列之外，绝大多数模型在上下文增长的过程中出现了生成质量的断崖式衰退。而每个模型的能力边界不同，意味着上下文管理很难直接适应所有模型和 Agent 系统。</li>
<li>另一个例子是“龙虾攻打月球”，有 Kimi 的工作人员表示用户应该利用缓存的机制来设计龙虾，并且尽量避开某一些时段以释放负载。上下文管理的复杂度意味着这个要求几乎是无厘头的，我甚至会批判这是一种偷懒行为。</li>
</ul>
<p>抽象泄漏是严重的系统设计问题，当利用某些既定的上下文管理机制处理这一切时，也意味着会存在足够多的手段打破系统的可靠性。</p>
<h2 id="geng-cong-ming-he-geng-shao-jia-she">更聪明和更少假设<a class="zola-anchor" href="#geng-cong-ming-he-geng-shao-jia-she" aria-label="Anchor link for: geng-cong-ming-he-geng-shao-jia-she" style="visibility: hidden;"></a>
</h2>
<p>bub 的设计最开始就没有考虑 “持续对话系统” ，我们考虑它在一个足够长的上下文上工作，也就是无尽的纸带。它在第一天就需要面临群聊中的社会化任务。问题不断出现，任务不断形成，又不断结束。在这样一个多样和复杂的场景中，每一轮对话都可能面临一个新的目标，它没有也无法要求存在某个永远延续的状态，甚至不存在必须继承的对话祖先。</p>
<p>回过头来看那个曾经让我害怕创造的想法，一条无尽的打孔纸带和上面的锚点，它在 bub 上运作良好，在越过上下文边界或者系统故障时，让我们有机会拥有足够简单和可靠的修复手段。</p>
<p>但是在现实任务之中，并不存在打孔纸带，也不会真的存在一个里程碑上的锚点。重点在于一个动作：构造，而不是继承。当一个任务出现，作为人类的我们也并不是把所有历史压进窗口里，而是做两件事——探索与选择。</p>
<ul>
<li>探索可能包括历史记录、外部系统、Memory、甚至即时查询。</li>
<li>选择则意味着丢弃大部分无关内容，只保留最小充分的材料。</li>
</ul>
<p>上下文工程默认的是递增，是延展，是管理膨胀。它假设状态必须被维护，于是引入缓存、提取、合并、压缩、分叉。每一层机制都在试图修补同一个前提：历史不能丢。但事实是它们无法携带足够多的历史。</p>
<p>bub 的实践给了我一个更简单的答案 —— 历史可以丢。更准确地说，历史不必默认继承。它只是素材库。需要时查询，不需要时忽略。</p>
<p>tape 的意义也在这里。它不是为了记录一切，而是为了允许“按需读取”。它把状态从“持续负担”变成“可选资源”。当上下文不再是递增函数，缓存就只是优化，而不是生命线；Memory 只是索引，而不是人格；会话只是边界，而不是身份。</p>
<p>所谓更聪明，不是引入更多机制。而是减少假设。</p>
<h2 id="da-dao-zhi-jian">大道至简<a class="zola-anchor" href="#da-dao-zhi-jian" aria-label="Anchor link for: da-dao-zhi-jian" style="visibility: hidden;"></a>
</h2>
<p>写下“被缚的普罗米修斯”这个标题时，我以为自己在批判一种束缚。</p>
<p>我们总是习惯用隐喻，把模型想象成被压抑的火种，被工程系统限制的力量。但也许问题没有那么戏剧化。模型并没有被囚禁。它只是被我们误用在一种错误的组织方式里。</p>
<p>任务出现，构造上下文，完成任务，结束。
下一轮重新开始。
当我们停止把系统建立在“延续状态”之上，很多复杂度会自然消失。</p>
<p>如果系统足够清晰，就不需要神话。
也不需要普罗米修斯。</p>
<hr />
<p>当然，每一种系统的出现，都意味着有依赖它所解决的问题存在，为了抒发观点，本文做了大量的批判，不代表它们是没有意义的。</p>
<p>另外再次感谢 bub 和我的朋友们，让我有机会更深刻地感受和表达这一切。</p>
<h2 id="tui-jian-yue-du">推荐阅读<a class="zola-anchor" href="#tui-jian-yue-du" aria-label="Anchor link for: tui-jian-yue-du" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="nofollow noreferrer external" href="https://frostming.com/posts/2026/create-a-claw/">创造一只龙虾，需要些什么?</a></li>
<li><a rel="nofollow noreferrer external" href="https://psiace.me/zh/posts/reinvent-the-punch-tape/">重新发明打孔纸带</a></li>
<li><a rel="nofollow noreferrer external" href="https://github.com/psiace/bub">bub</a></li>
<li><a rel="nofollow noreferrer external" href="https://www.piglei.com/articles/ai-programming-is-a-new-framework/">AI Programming Is a New Framework</a></li>
</ul>
重新发明打孔纸带
2026-01-28T00:00:00+00:00
2026-01-28T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/reinvent-the-punch-tape/
<blockquote>
<p>大家好，我是 <a rel="nofollow noreferrer external" href="https://github.com/PsiACE">PsiACE</a>，你可以在 GitHub 上找到我，这个想法最开始诞生于 4 个月前，那个时候我还在为更好的 GraphRAG 而努力。我过去几年在 Agent 和数据库有一些经验，你也可以阅读我的历史文章。</p>
</blockquote>
<h2 id="tl-dr">TL;DR<a class="zola-anchor" href="#tl-dr" aria-label="Anchor link for: tl-dr" style="visibility: hidden;"></a>
</h2>
<p>Agent 系统很容易走向复杂：分叉、回滚、长短期记忆、精心设计的压缩截断。</p>
<p>在工程上投入越多，行为越难以预测，我想是时候重新发明打孔纸带：Agent 只有一个确定的会话。它是永续的，不结束、不分叉，只是不断向前。在这个无尽的打孔纸带上，每次都能稳定地拿到此刻最需要的一小段上下文。</p>
<p><strong>让交互像真实世界一样自然地发生</strong>。</p>
<p>人与人之间的互动并不会真的分叉成多个同等真实的时间线，也不会通过回滚抹掉已经发生的事情。对话会跑题，会纠错，会换任务，会开始一个新阶段，但它始终发生在同一条连续的时间里。</p>
<h2 id="wu-jin-de-chang-zhi-dai">无尽的长纸带<a class="zola-anchor" href="#wu-jin-de-chang-zhi-dai" aria-label="Anchor link for: wu-jin-de-chang-zhi-dai" style="visibility: hidden;"></a>
</h2>
<p><strong>Agent 的基础应该是一条长纸带</strong>，是的，日志。</p>
<p>相比单纯的会话历史，日志中还应当记录发生过什么，一次工具结果、一次关键决策、一次阶段切换，都会作为事实被写入。事实一旦写入，就不再被修改，也不被有损替换。</p>
<p>你永远可以回到某个时间点，看到当时真实发生了什么，而不是一个后来被修订、压缩或重写过的版本。日志的意义不仅仅在是让模型读完历史，而在于让 Agent 的行为更容易验证。</p>
<p>在这条长纸带之上，<strong>Agent 计算状态</strong>。</p>
<p>自然地，我们应该使用从日志中计算出来的当前状态代替"记忆"，用来支持查询和上下文装配，而不是使用总结和压缩过的内容替代事实本身。它有点像数据库中的物化视图，可以被丢弃，也可以被重建，并且应该能够解释每一条状态从何而来。</p>
<p>在任何时候，系统只是重新选择一个起点，从日志重建状态，然后继续执行。</p>
<p>锚点正是为此引入的。</p>
<p>如果每次都从日志起点重建状态，系统最终会变得笨重，并且最终触发上下文限制。<strong>锚点提供了一组明确的重建起点</strong>，用来表达"从这里开始，状态已经足够稳定，可以继续工作"。锚点不删除历史，也不总结历史，它只是告诉系统从哪里开始算。</p>
<p>锚点通常由一次 handoff 产生。当 Agent 识别到阶段已经变化，或者继续沿用当前重建起点会让状态变得混乱时，它会执行一次 handoff：把对下一阶段仍然必要的最小结构化状态写入日志，创建一个新的锚点，之后的状态重建从新锚点开始。</p>
<p>这里打包的不是对历史的摘要，而是面向下一阶段的状态；历史仍然完整地留在日志里。线程没有断裂，也没有分叉，它只是继续向前。</p>
<h2 id="che-lun-gun-gun-xiang-qian">车轮滚滚向前<a class="zola-anchor" href="#che-lun-gun-gun-xiang-qian" aria-label="Anchor link for: che-lun-gun-gun-xiang-qian" style="visibility: hidden;"></a>
</h2>
<p><strong>Agent 并不真的分叉。</strong></p>
<p>分叉本质上是在制造多条同等真实的未来，但真实世界只有一个"现在"。你可以改变方向，但无法让已经发生的事情另起一条世界线。</p>
<p>许多看似需要分叉的场景，更自然的表达方式其实是 handoff。你不需要创建一条并行线程，而是承认自己进入了一个新阶段。你仍然在同一条线程上前进，只是从新的锚点开始重建状态。过去仍然存在于日志中，随时可以被查询和引用，但它不需要被变成一个并行世界。</p>
<p>同样地，<strong>Agent 并不真的回滚。</strong></p>
<p>回滚意味着撤销已经发生的事情，但在真实交互中，纠错并不是通过抹掉过去完成的，而是通过补充新的事实完成的。从工程角度看，回滚改变的是状态，而我们只允许用新事实改变状态，不允许让旧事实消失。</p>
<p>"回滚需求"的本质是上下文装配问题。你希望在本次执行中忽略某些片段，强调另一些片段，引导模型沿着不同方向推理。这不需要修改日志，也不需要回到旧状态，只需要在装配上下文时选择不同的工作集。</p>
<p><strong>Agent 也不真的依赖各种"记忆技巧"。</strong></p>
<p>多层摘要、反复压缩和复杂启发式规则在短期内可能有效，但长期会引入噪声、不确定性和不可解释性。你会越来越难区分哪些是事实，哪些是模型生成的概括，哪些是压缩后的残留误差。</p>
<p>检索和从历史中召回仍然是必要的。你可以从同一条线程的历史中取原文片段，也可以从外部数据源中取证据，把它们临时装配进本次上下文。但任何有损压缩都不应该悄悄替代历史。</p>
<h2 id="xin-de-da-kong-zhi-dai-ji-suan-ji">新的打孔纸带计算机<a class="zola-anchor" href="#xin-de-da-kong-zhi-dai-ji-suan-ji" aria-label="Anchor link for: xin-de-da-kong-zhi-dai-ji-suan-ji" style="visibility: hidden;"></a>
</h2>
<p>这套设计因此变得简单。</p>
<p>维护一条无尽向前的线程，并不断追加事实。用锚点表达阶段切换，用上下文装配控制每一次执行的窗口，并且允许从历史和外部数据源按需读取，并阻止有损结果成为新的真相。</p>
<p>Agent 应该充分利用我们过去在存储、计算等领域构建的一切，"更可靠的交互"将会胜过"更聪明的记忆"。</p>
我的 2025：All in DB 的第五年
2025-12-31T00:00:00+00:00
2025-12-31T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/my-2025-all-in-db-year-5/
<p>如果 21 年的五一没有崴到脚，我可能也不会一路从湖仓一体云原生走到向量多模 AI Native。
是的，2025 年是我在数据库行业摸爬滚打的第五个年头。
又到写年终总结的时候了，虽然前段时间狠狠地搞了一下「岁月史书」，但是该有的仪式感还是要的。</p>
<p>这次多谈谈自己。</p>
<h2 id="zhi-shi-tan-tan-gong-zuo">只是谈谈工作<a class="zola-anchor" href="#zhi-shi-tan-tan-gong-zuo" aria-label="Anchor link for: zhi-shi-tan-tan-gong-zuo" style="visibility: hidden;"></a>
</h2>
<p>我还是在一家数据库公司工作。
是的，「还是」意味着我又一次切换了工作。
12 月底的时候，我加入 OceanBase 从事数据库和 AI 生态相关的开源工作，
这已经是我职业生涯中的第三家数据库公司。</p>
<p>当然，在 NebulaGraph 做 GraphRAG 占据了 2025 的绝大多数时间。
尽管这个赛道已经过度拥挤并且不再火热，但我和团队里的其他同学在过去一年里还是交出了一份不错的答卷——
在特定领域的客户评测中能够达到 95% 的准确率，
总体开销也降低至可以对标向量全文混合索引，
几乎为基于图的文档类 RAG 的广泛应用铺平了道路。</p>
<p>至于工作派生出的产出也产生了一些积极的影响。
比如在 3 月份我调研集成 MCP 的时候，
设计和实现了 LlamaIndex 生态中的第一个 MCP 集成方案，
并且以 llama-index-tools-mcp 的形式贡献给上游。
在由社区进一步开发完善后，它成为了整个 Python 生态中下载量排在前 2% 的包。</p>
<p>我算不上一个醉心工作和研究的人。
若论代码品味，在过往共事过的同事中似乎也只算一般。
即便这样的我，也可以发光发热。
在 2025 年底的 NebulaGraph 社区评选中，也获得同事的肯定。
非常感谢大家的提携和帮忙，尽管江湖路远，终究还是会有机会再见面。</p>
<h2 id="yuan-kai-yuan-bi-you-ni-wo">愿开源庇佑你我<a class="zola-anchor" href="#yuan-kai-yuan-bi-you-ni-wo" aria-label="Anchor link for: yuan-kai-yuan-bi-you-ni-wo" style="visibility: hidden;"></a>
</h2>
<p>由于工作从事的 GenAI 平台是一个商业化产品，我参与开源的模式也发生了改变，
更多时候会从需求调研和落地的角度做一些事情，
前述的 llama-index-tools-mcp 就是这样的一个产物。</p>
<p>当然，我围绕 coding agent 做过一些探索。
参照 ampcode 的文章做了一个简单的 Python 实现，
它的后续演进的一些探索成为了在 PyCon China 2025 上的分享
《从 0 开始构建多 Agent 协作的命令行编程助手》的基石。</p>
<p>作为演讲中的一个片段，我介绍了自己为 agent client protocol 做的 Python SDK。
没有想过几个月后它会被 kimi-cli、openhands 等集成，
并且最终成为官方 SDK 的一员，单月下载量过百万，我也多刷新出一个新的维护者的身份。</p>
<p>我在 Apache 项目上也有一些投入。
将 OpenDAL 的几个子项目从 Repo 中拆了出来，
最近又在 DataSketches 的 Rust 实现上投入了一些无处安放的夜晚。</p>
<p>开源是否有我并不见得会更好或更糟糕，但我确确实实会从中汲取养分和动力。
哪些我曾经拥有过的美好一切，似乎就是在和开源伴生而来。
尽管我还有太多承诺过的事情被抛在脑后，没有办法及时兑现。</p>
<h2 id="ben-xiang-geng-mei-hao-de-sheng-huo">奔向更美好的生活<a class="zola-anchor" href="#ben-xiang-geng-mei-hao-de-sheng-huo" aria-label="Anchor link for: ben-xiang-geng-mei-hao-de-sheng-huo" style="visibility: hidden;"></a>
</h2>
<p>今年最重要的改变是：由于年底换到杭州工作，我总算结束了长达 4 年的异地恋爱，在第 8 个年头。
也解锁了更多和女朋友的美好的回忆，
比如在邓紫棋的演唱会上练习金鱼嘴，在五月天的演唱会被 wmls 投喂物料。</p>
<p>尝试通过学习来收获一些新技能。
虽然现在也还只是停留看着谱子弹《兰花草》的水平，
但至少又再一次能认得吉他和弦了。
练习了一段时间 house 舞种，
尽管跟上其他人的节奏对我已经是一个非常大的挑战，
但跟着节奏摇摆总是能让心情得到放松。</p>
<p>我有两只不那么可爱的猫咪。
有段时间一到凌晨就会扒拉开门跑到我的身上蹦迪。
坦白说，我没有把它们照顾很好。
但是枸杞还是一如既往地向我展露它的小肚皮，
芦荟在搬家到杭州以后也愿意偶尔凑过来吃一点点猫条。</p>
<p>生活啊，生活呵。
日日夜夜，但是提笔就不知道要写些什么了。
过得还算安好，也无甚风雨。
不久前的体检里似乎也没有再看到脂肪肝的影子。</p>
<h2 id="liu-yi-xie-bi-mo-gei-ai">留一些笔墨给 AI<a class="zola-anchor" href="#liu-yi-xie-bi-mo-gei-ai" aria-label="Anchor link for: liu-yi-xie-bi-mo-gei-ai" style="visibility: hidden;"></a>
</h2>
<p>除了一些效率、流程和节奏上的变化，我的工作和生活并没有因为 AI 而产生更多的波澜，
毕竟价值并不会因为多了一两个工具的介入就发生显著的偏移。</p>
<p>我没有打算统计我有多少代码是使用 AI 生成，过去一年到底花费了多少 token 或者费用。
但是，难得地，这是一篇 100% 我手打的文字。</p>
<p>世界在发生着深刻的变革，很荣幸能够参与其中，作为无数浪花中拍在石头上的一朵。</p>
聊聊测试自信
2025-12-25T00:00:00+00:00
2025-12-25T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/testing-confidence/
<p>在长期构建可被他人依赖的软件系统的过程中，我逐渐意识到，测试并不是一个单纯的质量保证工具，而是一种在维护者与用户之间建立信任边界的工程手段。</p>
<p>当一个系统缺乏这种边界时，复杂度并不会消失，而是会转移到维护者的判断、用户的使用成本，或双方的协作摩擦中。</p>
<p>对维护者来说，测试决定了系统是否还能被持续演进。
对用户来说，测试决定了系统是否值得被依赖。</p>
<p>而所谓“测试自信”，并不是来自某个测试指标，而是来自这两种视角是否通过测试被清晰地对齐。</p>
<h2 id="ce-shi-bing-bu-deng-jia-yu-fu-gai-lu">测试并不等价于覆盖率<a class="zola-anchor" href="#ce-shi-bing-bu-deng-jia-yu-fu-gai-lu" aria-label="Anchor link for: ce-shi-bing-bu-deng-jia-yu-fu-gai-lu" style="visibility: hidden;"></a>
</h2>
<p>在工程实践中，测试常常被简化为一些指标：覆盖率、CI 通过率、回归数量。
这些指标对维护者而言确实有直接价值，它们降低了修改代码时的不确定性。</p>
<p>但这些指标本身，并不能回答用户真正关心的问题：</p>
<blockquote>
<p>当系统被放入真实环境、真实负载和真实依赖中，它的行为是否是可预期的？</p>
</blockquote>
<p>系统一旦被他人使用，其使用方式几乎一定会偏离设计者的预期。
测试的价值，并不在于穷举所有路径，而在于通过一组可执行的用例，把系统的预期行为和边界条件显式固定下来。</p>
<p>当这些边界是清晰的：</p>
<ul>
<li>维护者知道哪些行为不能被破坏。</li>
<li>用户知道哪些行为可以被依赖。</li>
</ul>
<p>从这个角度看，测试并不是代码的附属物，而是连接维护者与用户的一层结构。</p>
<h2 id="ce-shi-shi-zai-dui-yu-yi-zuo-chang-qi-yue-shu">测试是在对语义做长期约束<a class="zola-anchor" href="#ce-shi-shi-zai-dui-yu-yi-zuo-chang-qi-yue-shu" aria-label="Anchor link for: ce-shi-shi-zai-dui-yu-yi-zuo-chang-qi-yue-shu" style="visibility: hidden;"></a>
</h2>
<p>在 Databend 的实践中，我们大量依赖现有数据库系统中已经被验证过的测试用例，并对关键基准进行长期跟踪，以此来固定实现对既有语义和标准的承诺。</p>
<p>一个重要的事实是：
系统复杂度的主要来源，并不是实现难度，而是语义在时间维度上的稳定性。</p>
<p>例如：</p>
<ul>
<li>某些异常条件下应返回结果还是错误。</li>
<li>不同执行路径是否满足相同的不变量。</li>
<li>一些并不优雅、但被大量使用的行为是否需要长期兼容。</li>
</ul>
<p>如果这些语义没有通过测试被固定下来，对维护者而言，它们会变成一种隐性负担。
每一次修改，都需要依赖记忆和经验来判断“这会不会破坏什么”。</p>
<p>而对用户来说，语义漂移带来的风险更加直接。
同样的用法，在不同版本中可能产生不同结果。</p>
<p>因此，测试在这里承担的角色，并不是“检查代码有没有 bug”，而是：</p>
<ul>
<li>为维护者提供清晰的演进边界。</li>
<li>为用户提供稳定的行为预期。</li>
</ul>
<p>这也是为什么像 MySQL、SQLite 这样的系统，会长期将测试视为高价值资产——因为测试本身承载的是对用户的长期承诺。</p>
<h2 id="ce-shi-shi-zai-xie-diao-wei-hu-zhe-pan-duan-yu-yong-hu-xian-shi">测试是在协调维护者判断与用户现实<a class="zola-anchor" href="#ce-shi-shi-zai-xie-diao-wei-hu-zhe-pan-duan-yu-yong-hu-xian-shi" aria-label="Anchor link for: ce-shi-shi-zai-xie-diao-wei-hu-zhe-pan-duan-yu-yong-hu-xian-shi" style="visibility: hidden;"></a>
</h2>
<p>在 Apache OpenDAL 的 CI 中，囊括了数百种不同的测试，提供对多平台和不同服务、binding 下的全面测试。
事实上，单一贡献者很难有精力自主筹备完整测试环境所需的一切依赖和服务。</p>
<p>如果说 Databend 的测试主要解决的是系统内外部语义的稳定性，那么在 Apache OpenDAL，测试更多是在解决维护者判断与用户现实之间的落差。</p>
<p>在对象存储生态里，很多服务都会声称自己是“S3 compatible”。
对维护者来说，只要实现了规范，就很容易形成一种假设：
系统在工程上“应该是可用的”。</p>
<p>但用户并不会在规范层面使用系统，他们只会在真实账户、真实服务、真实失败模式中使用它。
而大量问题，正是在这种假设与现实的落差中出现的。</p>
<p>因此，在 OpenDAL 中，我们始终坚持：</p>
<ul>
<li>尽可能使用真实服务进行测试。</li>
<li>不把文档和兼容性声明当作工程事实。</li>
<li>将失败用例长期保留，作为回归测试的一部分。</li>
</ul>
<p>这类测试的价值在于：</p>
<ul>
<li>它约束了维护者对外部世界的过度乐观判断。</li>
<li>也为用户提供了一个明确的信号：
哪些行为是已经在现实环境中被验证过、可以依赖的。</li>
</ul>
<p>在这里，测试并不是为了“证明实现正确”，而是为了让维护者的判断与用户的现实使用保持一致。</p>
<h2 id="ce-shi-zi-xin-rang-shuang-fang-dui-shi-bai-you-yi-zhi-li-jie">测试自信：让双方对“失败”有一致理解<a class="zola-anchor" href="#ce-shi-zi-xin-rang-shuang-fang-dui-shi-bai-you-yi-zhi-li-jie" aria-label="Anchor link for: ce-shi-zi-xin-rang-shuang-fang-dui-shi-bai-you-yi-zhi-li-jie" style="visibility: hidden;"></a>
</h2>
<p>在这些实践中，我逐渐形成了一个比较稳定的判断：</p>
<blockquote>
<p>测试自信，并不是系统“很少出问题”，而是当问题出现时，维护者和用户对问题的性质有一致的理解。</p>
</blockquote>
<p>当某种行为被测试覆盖时：</p>
<ul>
<li>对用户而言，失败意味着 bug。</li>
<li>对维护者而言，修复是明确的工程责任。</li>
</ul>
<p>而当某种行为从未被测试：</p>
<ul>
<li>对用户而言，它就不应被视为系统承诺。</li>
<li>对维护者而言，也不应被默认为必须长期兼容的行为。</li>
</ul>
<p>测试让这种区分变得清晰、可执行、可回归，也显著降低了双方在预期上的摩擦成本。</p>
<h2 id="jie-yu">结语<a class="zola-anchor" href="#jie-yu" aria-label="Anchor link for: jie-yu" style="visibility: hidden;"></a>
</h2>
<p>从工程角度看，测试并不是只为维护者服务的工具，也不是只为用户提供保障的机制，而是让双方在同一套行为边界上达成共识的结构。</p>
<p>它把隐含假设变成显式约束，把个人经验变成可以延续的工程边界。</p>
<p>对我而言，无论系统处在哪一层，测试最终都服务于同一件事：</p>
<blockquote>
<p>让系统在被依赖时是可预期的，
让维护在长期演进中是可持续的。</p>
</blockquote>
Live a Little · 下篇（2021 – 2025）
2025-11-29T00:00:00+00:00
2025-11-29T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/live-a-little-part-2/
<p><strong>赌城风云录</strong></p>
<p>这一篇是 21–25 年，也是和大多数朋友开始重叠的几年。
21 年是数据库风口，24 年是 AI 狂热，我也算都赶上了。
22–24 年我住在知名博彩城，标题就从那来。
名字或许遗漏，但心中也还记着，江湖再见请你喝茶。</p>
<hr />
<h2 id="shi-yi-pian">拾遗篇<a class="zola-anchor" href="#shi-yi-pian" aria-label="Anchor link for: shi-yi-pian" style="visibility: hidden;"></a>
</h2>
<p>早期我还写过一点前端。
用 JS 给 pitchfinder 贡献过 ACF2+ 音高检测算法，做过音频检测和可视化的小 demo。
还做过乐谱 OCR，把谱子转成乐符，再用 Java 库播放，挺好玩，只是淡了。
也做过以图搜图，提特征算相似度，试了很多组合纯粹好奇。</p>
<hr />
<h2 id="databend-pian">Databend 篇<a class="zola-anchor" href="#databend-pian" aria-label="Anchor link for: databend-pian" style="visibility: hidden;"></a>
</h2>
<p>我没数据库背景，是第一个校招生，还跳过面试。
有人问怎么做到的，我也说不清，只能感谢信任。</p>
<p>工作一半是工程，一半是社区。
工程是 Repo 级重构、依赖维护，偶尔写新功能。
社区源于我爱写爱分享，后来成了主线，大概分界点是落在去读书那段时间。</p>
<p>最早把测试从源码挪到外部单测，编译更快更干净，但要多切文件，也加了心智负担。
随着代码几年来涨得快，又做了一轮拆分提并行和质量。
sundy-li 主导的几次大规模的重构我也有参与，从 reddit 帖子发掘 <code>arrow2</code> ，后来又受迟先生搞类型体操的启发。</p>
<p>云平台的 f 叔、之晗写的 OKR 对齐文档，让我第一次感到规范节奏，于是不久后，我们就有一个可以内部把玩的云平台原型。
我还提过一个基准测试的方案，把结果写成 json 保存到 repo ，再进行可视化。
早期 Databend 像一个巨大的练习场，我几乎摸过所有角落，也开始了解数据系统该怎么呼吸。</p>
<hr />
<h2 id="apache-opendal-pian">Apache OpenDAL 篇<a class="zola-anchor" href="#apache-opendal-pian" aria-label="Anchor link for: apache-opendal-pian" style="visibility: hidden;"></a>
</h2>
<p>我和漩涡认识于他处理官网迁移的时候。
当时的存储访问层是 dal，应该是老赵设计的，但是我们需要兼顾对象存储和 HDFS。
漩涡建议重写成通用接口，于是他做了 dal2，后来独立出来成为 opendal。</p>
<p>菜菜子做了早期 WebHDFS 的集成，Databend 也顺势补了 hive 支持。
数据公司大抵都有一些类似的需求，opendal 被不少友商关注，在 tison 的帮助下进入基金会孵化。</p>
<p>在 opendal 前，我只是拿工资写开源。
在这里，我体验到不用利润目标也能靠信任合作，“community over code”。</p>
<hr />
<h2 id="du-cheng-qiu-xue">赌城求学<a class="zola-anchor" href="#du-cheng-qiu-xue" aria-label="Anchor link for: du-cheng-qiu-xue" style="visibility: hidden;"></a>
</h2>
<p>全职一年后我去澳门读应用数学与数据科学。
可能是宅久了，也可能是觉得还不够好，总之想出去看看。</p>
<p>数学课很多，上一节课要掉不少头发，好在最后也一路学过了凸优化。
AI 和大模型这时候也开始进入到我的学习和生活：利用 Meta 的 SAM 做分割，结合 CLIP 做交互式 caption，在 nanogpt 上改模型结构、优化器和学习率调度。</p>
<p>和 Databend 的联系仍然紧密：编译和 Rust 优化，做过几次分享；探索分析 lakeFS、HuggingFace 的数据；做 kubesphere 4.0 集成和 databend playground；办过线上 hackathon；管大部分中文文档，维护大模型转写英文文档的工作流；当时还面临企业版功能的源代码是否应该开放的讨论，我也翘课参加。</p>
<p>23 年 Apache Con 第一次线下见到 Xuanwo，我们各讲一个 OpenDAL 主题。
他是第一个给我寄过喜糖的同事，我也偶尔充当他的合并机器人。
那次还见到 tison、saka、f 叔、xp，还和 TCeason 一起去了颐和园。
后来又有机会见到之晗、Eric；Rust conf 认识 RisingWave 的朋友，很多 ID 和面容有了映射。</p>
<p>24 年去日本玩了一圈后专心毕设，主题是现代缓存替换算法。
和 juncheng 聊过一次，他主导了 sieve、s3fifo 等几个非常简洁有趣的算法设计。
毕业迫使我收拢精力，那是一段煎熬的时刻，还好我的导师总是以一副宁静的姿态出现。
我顺利毕业，也离开了 Databend，最后一次公开分享是《面向现代分层存储的 Caching 技术漫谈》。</p>
<hr />
<h2 id="nebulagraph-pian">NebulaGraph 篇<a class="zola-anchor" href="#nebulagraph-pian" aria-label="Anchor link for: nebulagraph-pian" style="visibility: hidden;"></a>
</h2>
<p>离开 Databend 之后要再找工作。
我还想做 data infra，也想过投递一些不那么技术的岗位。
市场很冷，两家同行业公司一路面到 CXO 也没结果。
大厂面试不算投机，面试官对我的经历不太感冒，我也没有过多准备在算法和八股上。
朋友介绍了几家 web3，虽然拿到高薪 offer 但还是顾虑合规问题，只能作罢。</p>
<p>转机在杭州 Apache Con。
我见到几个 Graph 厂商的朋友，从慧姐和盐粒的口中才知道 NebulaGraph 的 GenAI 团队在招人，leader 是多年的推友 wey-gu。
最后一轮是 sherman，除了常规问答，还考了一道口述算法，很难想到这会出现在文化相性的面试上。</p>
<p>入职前我去上海参加 Rust Conf，也顺便认认上海办公室的位置。终于见到 yihong0618，一个非常有趣的灵魂。也第一次见到 RisingWave 的其他朋友，叉鸽（foyer-rs）、润基（arrow-udf），6 个月后在 KCD Beijing，我还去了他们的北京办公室，吃到了美味的小鱼干。
PyCon China 2024 上，wey 做主题分享，我认识了 frostming、晋涛，还和粉头发 saka 合了影。
到了 2025 的 Rust Conf 上，有机会见到雷少和 andy ，他们和 tison 一起创业做新产品。
再晚一点的 PyCon 我便有了一个讲 coding agent 的主题，和好多群友也是这次相会。</p>
<p>业余收获也多：
做了 llama index 社区的第一个 mcp 集成方案，并且贡献了第一版实现到官方 repo；
写了第一个 agentclientprotocol Python SDK，在 JetBrains 朋友帮助下成了官方 SDK；
还拜访了他们上海办公室，拎了一筐周边回家。</p>
<p>我们从浦东搬到南京西路，从小黑屋搬到阳光间。
慧姐离开去了 oceanbase，wey 离职创业做 nowledage memory，
我和盐粒继续在 graph rag 和 agent 上折腾，落地了当初想的 Fusion GraphRAG。
邵老师负责端到端评估，坚持先把召回率和准确率搞上去。
它让 GraphRAG 的上手成本接近向量或全文 RAG，并且在一些领域问答准确率到 95%+。</p>
<hr />
<h2 id="wei-sheng">尾声<a class="zola-anchor" href="#wei-sheng" aria-label="Anchor link for: wei-sheng" style="visibility: hidden;"></a>
</h2>
<p>时间走到 2025 年末，好像也就到这里了。</p>
Agent Client Protocol Python SDK 的新篇章
2025-11-07T00:00:00+00:00
2025-11-07T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/acp-python-sdk-new-chapter/
<p>当我最初开始编写 <strong><a rel="nofollow noreferrer external" href="https://github.com/agentclientprotocol/python-sdk">Agent Client Protocol Python SDK</a></strong> 时，它只是一个出于好奇的小项目。
我想弄清楚 <em>coding agents</em> 是如何交流的——状态、意图与消息在客户端和智能体之间如何流动。</p>
<p>随着时间推移，它逐渐成长为一个真正有用的项目。
越来越多的开发者开始使用它，从 <strong>Moonshot</strong> 到其他探索智能体工作流的公司。
SDK 的架构变得稳定，并持续与 ACP 规范保持同步，成为多种实际集成的基础。</p>
<p>今天，是一个新的开始。
Python SDK 已经正式迁移到 <strong><a rel="nofollow noreferrer external" href="https://github.com/agentclientprotocol">agentclientprotocol</a></strong> 组织下，与 TypeScript、Rust、Kotlin SDK 一起成为官方生态的一部分。</p>
<p>我会继续在新组织下维护和改进它，专注于让它更加可靠、简洁、易于集成，让更多开发者能够轻松构建智能体系统。</p>
<p>特别感谢 <strong>Sergey Ignatov</strong>、<strong>Anna</strong> 和 <strong>Ben</strong> 在整个迁移过程中给予的信任与支持，也感谢所有曾经使用、贡献或反馈过这个项目的开发者们。</p>
<p>这个项目最初只是一个实验，如今它已成为一个共同的努力。
愿我们一起迎接新的篇章。</p>
<p>— <strong>尚卓燃（PsiACE）</strong>
Maintainer, ACP Python SDK</p>
Live a Little · 上篇（2016 – 2021）
2025-10-20T00:00:00+00:00
2025-10-20T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/live-a-little-part-1/
<p><strong>在代码与青春之间</strong></p>
<blockquote>
<p>我即将二十七岁。
按新时代的算法，已经稳稳进入「老登」序列。
这一年，我的第二份正式工作也满了一年多。
回头看，想聊聊那些年我和代码之间的故事。</p>
</blockquote>
<hr />
<h2 id="2016-shao-nian-yi-qi-yu-di-yi-xing-dai-ma">2016：少年意气与第一行代码<a class="zola-anchor" href="#2016-shao-nian-yi-qi-yu-di-yi-xing-dai-ma" aria-label="Anchor link for: 2016-shao-nian-yi-qi-yu-di-yi-xing-dai-ma" style="visibility: hidden;"></a>
</h2>
<p>把时间拨回 2016 年。
那时我沉迷小说，读过的大部头早已按「车载斗量」计。
Ruby 风头正盛，我用 Rails 搭过小站，也在 GitHub 上部署过 Jekyll 生成的静态页。
想写漂亮 UI 的冲动驱使我去学 HTML；
我偷偷读完了 <em>Digital Design and Computer Architecture</em> ——一本讲 Verilog HDL 和计算机体系结构的书。
那时我并不真正懂，只是怀着一点少年心气。</p>
<hr />
<h2 id="2017-2018-da-xue-suan-fa-yu-chu-lian">2017 – 2018：大学、算法与初恋<a class="zola-anchor" href="#2017-2018-da-xue-suan-fa-yu-chu-lian" aria-label="Anchor link for: 2017-2018-da-xue-suan-fa-yu-chu-lian" style="visibility: hidden;"></a>
</h2>
<p>2017 年，我进入大学，主修计算机科学与技术。
学校很大，疫情前的校车也只能遍历小半个校区。
数学天赋平平，但我仍喜欢编程——因为它让我能「造点什么」。</p>
<p>2018 年，我试图认真地学算法与英语，已经在 Linux 环境下生活。
我读 GNU 和自由软件基金会的故事，也在 GNU.org 帮忙校对文章。
那时的我还不会 git 之外的工具，全靠前辈帮我合并推送。
在邮件列表里，我看到俊余的名字——几年后，他做的 WebP 图像服务在推特上火爆一时。</p>
<p>同年我写信给刚落地中国的 <a rel="nofollow noreferrer external" href="https://leetcode.cn/">LeetCode 力扣</a>，想参与题解翻译。
Hercy 给我了第一封正式回复。
和 Winston 一起帮我做了 landing 。
如今一晃也结缘七年。</p>
<p>当然，2018 也有更多故事：
我挂了高数，也遇见了现在的女朋友。
那年秋天我和工作室的朋友一起看《昨日青空》，出来吃小吃时我说：</p>
<blockquote>
<p>「这电影该和女生一起看。」
后来我又买了两张票，和学妹二刷——
转眼，我们已经在一起七年。</p>
</blockquote>
<p>技术上，18 年我第三次重生 GitHub 账号，尝试 Rust 项目 Servo，学 Cargo 命令，修 README 里的构建流程。
当时谁能想到，我未来有一段工作会真正用 Rust 写代码。</p>
<hr />
<h2 id="2019-fan-yi-she-qu-yu-zao-qi-xiang-mu">2019：翻译、社区与早期项目<a class="zola-anchor" href="#2019-fan-yi-she-qu-yu-zao-qi-xiang-mu" aria-label="Anchor link for: 2019-fan-yi-she-qu-yu-zao-qi-xiang-mu" style="visibility: hidden;"></a>
</h2>
<p>翻译比我想的走得更远。
2019 年，<a rel="nofollow noreferrer external" href="https://linux.cn/lctt/">LCTT</a> 仍是国内最活跃的 Linux 中文社区。
我在里面结识了老王和白宦成老师；我们计划合写一本书，虽最终搁浅，但那段共同写作的日子至今难忘。</p>
<p>技术上，Python 当时如日中天。
我学了 Flask、Django、FastAPI 皮毛，用 Cookiecutter 生成项目模板。
后来成为 <a rel="nofollow noreferrer external" href="https://github.com/audreyfeldroy/cookiecutter-pypackage">audreyfeldroy/cookiecutter-pypackage</a> 的维护者——一个几千 star 的项目。
她和 Pydanny 是有名的「夫妻店」，今天依然活跃。</p>
<p>年底，我修完编译原理课，读 <em>Crafting Interpreters</em>，写了个 C 语言项目的模板 <a rel="nofollow noreferrer external" href="https://github.com/PsiACE/meco">meco</a> 和玩具语言 <a rel="nofollow noreferrer external" href="https://github.com/PsiACE/emo">emo</a>。
那时也尝试 Neo4j 与 NebulaGraph，做过可视化图查询的项目。
我没想到，几年后我真会在图数据库公司工作。</p>
<hr />
<h2 id="2020-rust-zhi-xia-yu-fang-xiang-chu-ding">2020：Rust 之夏与方向初定<a class="zola-anchor" href="#2020-rust-zhi-xia-yu-fang-xiang-chu-ding" aria-label="Anchor link for: 2020-rust-zhi-xia-yu-fang-xiang-chu-ding" style="visibility: hidden;"></a>
</h2>
<p>2020 准备考研，但心思其实一半在代码。
我从 Python 转向 Rust，入选首届 <a rel="nofollow noreferrer external" href="https://summer-ospp.ac.cn/">开源之夏 OSPP</a>，在 Casbin 写了 <a rel="nofollow noreferrer external" href="https://github.com/casbin-rs/casbin-raft">casbin-raft</a>，认识了江成和 Hackerchai。
江成后来为我写了推荐信，chai 去了 Kong。
和 OSPP 的缘分甚至更深，一直延续到今天。</p>
<p>同年，我在 Rust 中文社区贡献翻译：
译过 <em>Writing an OS in Rust</em> 中的一章，与洛佳结识——后来他做了 <a rel="nofollow noreferrer external" href="https://github.com/rustsbi/rustsbi">RustSBI</a>。
我还翻译了 nrc 的 <em>“Early Impressions of Go from a Rust Programmer”</em> 。
PingCAP 的 VLDB 论文成为了毕设开题材料。
这个内容在获得授权后发布在了 <a rel="nofollow noreferrer external" href="https://github.com/psiace/tidb-a-raft-based-htap-database">PsiACE/TiDB-A-Raft-based-HTAP-Database</a></p>
<p>毕业设计题是 “基于 Rust 的分布式 KV”——Raft + Bitcask。
熟悉 PingCAP 的同学应该都知道灵感出自何处。
我研究 async-raft（即 <a rel="nofollow noreferrer external" href="https://github.com/datafuselabs/openraft">databend/openraft</a> 前身），也给 P 社周边库提 PR。
那年我以个人捐赠者身份支持 <a rel="nofollow noreferrer external" href="https://rustcc.cn/2020rustchinaconf/">Rust China Conf 2020</a>，和夏歌、Mike、汉东有了更多交流。
后来，我还做了几年 Rust 中文社区日报编辑。</p>
<hr />
<h2 id="2021-zhuan-zhe-yu-di-yi-fen-gong-zuo">2021：转折与第一份工作<a class="zola-anchor" href="#2021-zhuan-zhe-yu-di-yi-fen-gong-zuo" aria-label="Anchor link for: 2021-zhuan-zhe-yu-di-yi-fen-gong-zuo" style="visibility: hidden;"></a>
</h2>
<p>考研失败——毕竟我复习间隙还在给 <a rel="nofollow noreferrer external" href="https://github.com/xi-editor/xi-editor">xi-editor</a> 修过 lint。
我去 Wasmedge 面试实习，了解到了 WebAssembly 和 ERC20 标准，我修正的方案最后被用于社区。
又从 Meilisearch 和 Hashlink 分叉出 <a rel="nofollow noreferrer external" href="https://github.com/PsiACE/riteraft">riteraft</a> 和 <a rel="nofollow noreferrer external" href="https://github.com/PsiACE/ritelinked">ritelinked</a>，前者积累 300 多 star，后者成为我下载量最高的 crate 之一。</p>
<p>我也拿到 PingCAP 面试机会，当时项目是给 <a rel="nofollow noreferrer external" href="https://github.com/pingcap/tichi">Tichi</a> 做贡献。
练习部署 Prow 时，第一次切身感受国内网络之艰难。
Mini256 就在那个组里——几年后，我在做 GraphRAG 时看到 TiDB 推出 AutoFlow，他也在做 RAG 了。</p>
<p>那段时间，我一边写论文，一边给 <a rel="nofollow noreferrer external" href="https://github.com/datafuselabs/databend">Databend</a> 做早期贡献，从 CI 到模糊测试，再到上游的 Arrow 和 SQL 解析器。
那时 Databend 不过 10 人左右。
我加了虎哥好友，只想向技术大佬多学习，没想到真的因此获得了工作机会。
他爽快地约我在武汉见面。
我至今记得那天的阳光——
那是创业者最有光的年纪。</p>
<p>6 – 7 月间，我在 Databend 上下游提了约 40 个 PR。
就这样，我加入了这个立志打造“中国版 Snowflake”的团队，开始了我的第一份真正意义上的工程师工作。</p>
<hr />
<blockquote>
<p><em>未完待续 —— Part 2 将讲述 2022 至 2025，从 Databend 到 Apache OpenDAL 等这些年的故事。</em></p>
</blockquote>
用 Spec 做 SDK - 生成式 AI 的时代
2025-10-15T00:00:00+00:00
2025-10-15T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/spec-driven-sdks/
<blockquote>
<p>AI 写得快，但容易膨胀；
Spec 很严格，但可能僵化。</p>
<p>我选择中间那条路——
让 AI 在边界内跑，让人对结果负责。</p>
</blockquote>
<h2 id="wei-shen-me-bu-shi-quan-ai-ye-bu-shi-quan-spec">为什么不是全 AI，也不是全 Spec<a class="zola-anchor" href="#wei-shen-me-bu-shi-quan-ai-ye-bu-shi-quan-spec" aria-label="Anchor link for: wei-shen-me-bu-shi-quan-ai-ye-bu-shi-quan-spec" style="visibility: hidden;"></a>
</h2>
<p>AI 写代码的速度让人上瘾；一旦规模扩大，很容易出现上下文漂移、结构膨胀、边界模糊——项目“能跑但不稳”。</p>
<p>另一个极端是 spec 驱动：严谨，但往往过重。GitHub 推出的 <a rel="nofollow noreferrer external" href="https://github.com/github/spec-kit">Spec Kit</a> 倡导“先规范再生成”，对快速迭代的团队并不总是友好，容易过度设计、难以跟踪决策。</p>
<p>我走中间态：在维护 <a rel="nofollow noreferrer external" href="https://agentclientprotocol.com">Agent Client Protocol (ACP)</a> 的 <a rel="nofollow noreferrer external" href="https://github.com/psiace/agent-client-protocol-python"><strong>Python SDK</strong></a> 时，用规范约束 AI 生成，用 AI 加速规范适配。</p>
<h2 id="acp-wei-sdk-er-sheng-de-xie-yi">ACP：为 SDK 而生的协议<a class="zola-anchor" href="#acp-wei-sdk-er-sheng-de-xie-yi" aria-label="Anchor link for: acp-wei-sdk-er-sheng-de-xie-yi" style="visibility: hidden;"></a>
</h2>
<p>ACP 由 <a rel="nofollow noreferrer external" href="https://zed.dev/blog/bring-your-own-agent-to-zed">Zed</a> 发起，定义<strong>编辑器 ↔ Agent</strong> 的通信方式。
它采用 <a rel="nofollow noreferrer external" href="https://www.jsonrpc.org/specification">JSON-RPC 2.0</a> 作为通信机制，并以 <strong>JSON Schema</strong> 描述数据结构（典型 schema 见 ACP 仓库）。边界明确、类型可机读、行为可审计——天生适合需要跨语言、长期维护的 SDK。</p>
<h2 id="wo-de-shi-xian-guo-cheng">我的实现过程<a class="zola-anchor" href="#wo-de-shi-xian-guo-cheng" aria-label="Anchor link for: wo-de-shi-xian-guo-cheng" style="visibility: hidden;"></a>
</h2>
<h3 id="qi-dian-zui-xiao-ke-yong-ti-mvp">起点：最小可用体（MVP）<a class="zola-anchor" href="#qi-dian-zui-xiao-ke-yong-ti-mvp" aria-label="Anchor link for: qi-dian-zui-xiao-ke-yong-ti-mvp" style="visibility: hidden;"></a>
</h3>
<p>我给自己三条约束（大量使用 Coding Agent，统一由我把边界与审阅）：</p>
<ol>
<li>基于 datamodel 生成 <strong>Pydantic</strong> 模型（<a rel="nofollow noreferrer external" href="https://docs.pydantic.dev/latest/">pydantic.dev</a>）。</li>
<li>实现最小 I/O（JSON-RPC over stdio）。</li>
<li>迁移文档示例与基本测试，由我负责核对与回归。</li>
</ol>
<p>体量刻意保持小：<strong>先上线，尽快暴露问题</strong>。</p>
<h3 id="die-dai-cong-fan-kui-zhong-chang-chu-jie-gou">迭代：从反馈中长出结构<a class="zola-anchor" href="#die-dai-cong-fan-kui-zhong-chang-chu-jie-gou" aria-label="Anchor link for: die-dai-cong-fan-kui-zhong-chang-chu-jie-gou" style="visibility: hidden;"></a>
</h3>
<p>早期用户反馈“命名不一致、使用不顺手”。
我让 agent 扫描文档生成 <strong>rename map</strong>（统一 Python 化命名），并对照其他语言实现取长补短：</p>
<ul>
<li>TypeScript SDK 里 <strong>helpers</strong>（降低重复样板）。</li>
<li>Go SDK 用 <strong>golden tests</strong>（固定请求/响应样张做回归）。</li>
<li>Rust SDK 的模块组织更克制。</li>
<li>其他协议类 SDK（如 <a rel="nofollow noreferrer external" href="https://modelcontextprotocol.io/">MCP</a>）采用相似的协议，值得借鉴。</li>
</ul>
<p>在 agent 协助下完成结构与测试重组，由我把控标准与审阅路径。</p>
<h3 id="lu-you-hua-ti-dai-if-pan-duan">路由化：替代 if 判断<a class="zola-anchor" href="#lu-you-hua-ti-dai-if-pan-duan" aria-label="Anchor link for: lu-you-hua-ti-dai-if-pan-duan" style="visibility: hidden;"></a>
</h3>
<p>我不想看到满屏的 <code>if method == "..."</code>，于是写了极简路由，把“方法名 → 处理器”变成一等公民：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>builder</span><span class="z-keyword"> =</span><span> RouterBuilder</span><span>(</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>builder</span><span>.</span><span>request_attr</span><span>(</span><span class="z-constant">CLIENT_METHODS</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">fs_write_text_file</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>,</span><span> WriteTextFileRequest</span><span>,</span><span> client</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">writeTextFile</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span>builder</span><span>.</span><span>request_attr</span><span>(</span><span class="z-constant">CLIENT_METHODS</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">fs_read_text_file</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>,</span><span> ReadTextFileRequest</span><span>,</span><span> client</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">readTextFile</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span></code></pre>
<p>到 <code>v0.4.9</code>，体量不大，但代码 <strong>稳定且可教学</strong>。</p>
<h2 id="shang-xia-wen-jian-xuan-rang-ai-chi-dui-dong-xi">上下文拣选：让 AI 吃对东西<a class="zola-anchor" href="#shang-xia-wen-jian-xuan-rang-ai-chi-dui-dong-xi" aria-label="Anchor link for: shang-xia-wen-jian-xuan-rang-ai-chi-dui-dong-xi" style="visibility: hidden;"></a>
</h2>
<p>我把提示词上下文当“工程预算”管理：只喂必要信息、限定边界，并对版本负责。</p>
<ul>
<li><strong>上下文清单（manifest）</strong>：只列 schema、公共接口与最小示例；排除生成代码与外部依赖。</li>
<li><strong>Diff 感知</strong>：只给改动的 hunk 与少量前后文（5–15 行），而不是整文件。</li>
<li><strong>黄金片段索引</strong>：提示 agent 自检索必要片段，避免大段粘贴。</li>
<li><strong>先立护栏</strong>：明确“不得臆造 schema 字段；失败优先；缺信息先询问”。</li>
</ul>
<h2 id="fang-fa-lun-spec-yu-ai-de-xie-zuo">方法论：Spec 与 AI 的协作<a class="zola-anchor" href="#fang-fa-lun-spec-yu-ai-de-xie-zuo" aria-label="Anchor link for: fang-fa-lun-spec-yu-ai-de-xie-zuo" style="visibility: hidden;"></a>
</h2>
<table><thead><tr><th style="text-align: left">原则</th><th style="text-align: left">说明</th></tr></thead><tbody>
<tr><td style="text-align: left"><strong>生成与人工治理分离</strong></td><td style="text-align: left">模型自动生成，业务由人编排与审阅，不混用。</td></tr>
<tr><td style="text-align: left"><strong>从最小可用体开始</strong></td><td style="text-align: left">用真实反馈驱动人体工学优化。</td></tr>
<tr><td style="text-align: left"><strong>Golden Test</strong></td><td style="text-align: left">捕获/回放请求与响应，作为回归与审计基线。</td></tr>
<tr><td style="text-align: left"><strong>上下文拣选与预算</strong></td><td style="text-align: left">只喂必要上下文，小而准、可复现。</td></tr>
</tbody></table>
<p>规范给 AI 以边界；AI 让规范鲜活起来。</p>
<h2 id="ze-ren-gan-wei-shen-me-wo-gan-dui-ai-xie-de-dai-ma-fu-ze">责任感：为什么我敢对 AI 写的代码负责<a class="zola-anchor" href="#ze-ren-gan-wei-shen-me-wo-gan-dui-ai-xie-de-dai-ma-fu-ze" aria-label="Anchor link for: ze-ren-gan-wei-shen-me-wo-gan-dui-ai-xie-de-dai-ma-fu-ze" style="visibility: hidden;"></a>
</h2>
<p>AI 能写，但边界我来定义。
有强类型模型、可复现测试、可回放轨迹，我可以验证每一步。
我信任的不是模型，而是 <strong>它背后的工程纪律</strong> 。</p>
<h2 id="wo-zai-pr-li-de-shuo-ming">我在 PR 里的说明<a class="zola-anchor" href="#wo-zai-pr-li-de-shuo-ming" aria-label="Anchor link for: wo-zai-pr-li-de-shuo-ming" style="visibility: hidden;"></a>
</h2>
<p>这段说明最早见于 <a rel="nofollow noreferrer external" href="https://github.com/Xuanwo">@xuanwo</a> 的 PR。我之前没有这样写，但我愿意采用这种方式——因为我对结果负责。在这个 SDK 的工作中我大量使用了 AI；<strong>边界与质量由我把关</strong>：</p>
<blockquote>
<p><strong>This PR was primarily authored with GPT-5-Codex and hand-reviewed by me.
I’m responsible for every change that lands here.</strong></p>
</blockquote>
<p>这不是“炫 AI”，而是<strong>结果负责的声明</strong>。</p>
<h2 id="jie-yu-su-du-yu-gui-dao">结语：速度与轨道<a class="zola-anchor" href="#jie-yu-su-du-yu-gui-dao" aria-label="Anchor link for: jie-yu-su-du-yu-gui-dao" style="visibility: hidden;"></a>
</h2>
<p>AI 是燃料，Spec 是轨道。
燃料给你速度，轨道让你抵达。</p>
<p>我喜欢这种平衡：模型来写，我来设边界。
每一行可解释，每一次失败可复现。
这就是在人工智能时代负责任地构建方式。</p>
<p>— <strong>PsiACE</strong> （<a rel="nofollow noreferrer external" href="https://github.com/PsiACE">GitHub</a> · <a rel="nofollow noreferrer external" href="https://opendal.apache.org/">Apache OpenDAL PMC Member</a>）</p>
ACP：交互契约与 Python SDK
2025-09-08T00:00:00+00:00
2025-09-08T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/acp-and-python-sdk/
<h2 id="tl-dr">TL;DR<a class="zola-anchor" href="#tl-dr" aria-label="Anchor link for: tl-dr" style="visibility: hidden;"></a>
</h2>
<ul>
<li>ACP（Agent Client Protocol）是“客户端 ↔ 智能体”之间的交互契约，定义会话、内容块、工具调用、计划、文件系统等语义。</li>
<li>Zed 以 ACP 为核心，让内置与外部智能体共享同一套 UX，开发者只需实现一次协议即可通吃多个宿主。</li>
<li>我写了 Python SDK：<code>pip install agent-client-protocol</code>，提供 Pydantic 模型、<code>AgentSideConnection</code>、stdio helper，帮你快速接上。</li>
<li>这是一场标准化竞赛。ACP 与 MCP、A2A、AG-UI 互补又竞合，谁先积累生态谁就有话语权。</li>
</ul>
<h2 id="acp-jie-jue-liao-shen-me">ACP 解决了什么<a class="zola-anchor" href="#acp-jie-jue-liao-shen-me" aria-label="Anchor link for: acp-jie-jue-liao-shen-me" style="visibility: hidden;"></a>
</h2>
<p>ACP 不只是“一条管道”，它规定：</p>
<ul>
<li>传输层用 JSON-RPC，支持流式更新；</li>
<li>会话生命周期（new/load/prompt/cancel）清晰；</li>
<li>内容块支持文本、图片、音频、资源链接等；</li>
<li>工具调用与更新（<code>tool_call</code> / <code>tool_call_update</code>）格式统一；</li>
<li>文件读写、任务计划、状态同步都有规范字段。</li>
</ul>
<p>换句话说，宿主（如 Zed）与智能体之间的 UX 语义不再每家重造，体验可以搬家。</p>
<h2 id="yu-qi-ta-biao-zhun-de-guan-xi">与其他标准的关系<a class="zola-anchor" href="#yu-qi-ta-biao-zhun-de-guan-xi" aria-label="Anchor link for: yu-qi-ta-biao-zhun-de-guan-xi" style="visibility: hidden;"></a>
</h2>
<ul>
<li><strong>AG-UI</strong>：同样关注交互层，部分语义重合，可能会出现“互转/共存”的场景。</li>
<li><strong>MCP</strong>：负责工具和资源接入，适合与 ACP 搭配使用（工具能力来自 MCP，交互流程由 ACP 承载）。</li>
<li><strong>A2A</strong>：聚焦智能体之间的通信，后续也可能与 ACP 对接。</li>
</ul>
<h2 id="zed-de-shi-jiao">Zed 的视角<a class="zola-anchor" href="#zed-de-shi-jiao" aria-label="Anchor link for: zed-de-shi-jiao" style="visibility: hidden;"></a>
</h2>
<ul>
<li>使用者：可以把 Claude Code、Gemini CLI、内部 Agent 统统接进编辑器，享受一致的流式体验和工具栏。</li>
<li>开发者：写一次 ACP，就能跑在任何支持它的宿主上，减少重复 glue code。</li>
<li>平台：通过协议锁定体验，生态统一，支持成本下降。</li>
</ul>
<h2 id="python-sdk-ti-gong-liao-shen-me">Python SDK 提供了什么<a class="zola-anchor" href="#python-sdk-ti-gong-liao-shen-me" aria-label="Anchor link for: python-sdk-ti-gong-liao-shen-me" style="visibility: hidden;"></a>
</h2>
<p>安装：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">pip</span><span class="z-string"> install</span><span class="z-string"> agent-client-protocol</span></span></code></pre>
<p>功能：</p>
<ul>
<li>Pydantic v2 模型：schema 都有类型提示；</li>
<li><code>AgentSideConnection</code> / <code>ClientSideConnection</code>：分别处理智能体端与客户端；</li>
<li>stdio helper：适合 CLI/本地进程场景；</li>
<li>与官方 schema 对齐，严格校验。</li>
</ul>
<h3 id="zui-xiao-echo-agent">最小 Echo Agent<a class="zola-anchor" href="#zui-xiao-echo-agent" aria-label="Anchor link for: zui-xiao-echo-agent" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> asyncio</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> acp</span><span class="z-keyword"> import</span><span> Agent</span><span>,</span><span> AgentSideConnection</span><span>,</span><span> stdio_streams</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> acp</span><span class="z-keyword"> import</span><span> InitializeRequest</span><span>,</span><span> InitializeResponse</span><span>,</span><span> NewSessionRequest</span><span>,</span><span> NewSessionResponse</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> acp</span><span class="z-keyword"> import</span><span> PromptRequest</span><span>,</span><span> PromptResponse</span><span>,</span><span> AuthenticateRequest</span><span>,</span><span> LoadSessionRequest</span><span>,</span><span> CancelNotification</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> EchoAgent</span><span>(</span><span class="z-entity">Agent</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> initialize</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> params</span><span>:</span><span> InitializeRequest</span><span>)</span><span> -></span><span> InitializeResponse</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> InitializeResponse</span><span>(</span><span class="z-variable">protocolVersion</span><span class="z-keyword">=</span><span>params</span><span>.</span><span>protocolVersion</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> newSession</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> params</span><span>:</span><span> NewSessionRequest</span><span>)</span><span> -></span><span> NewSessionResponse</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> NewSessionResponse</span><span>(</span><span class="z-variable">sessionId</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">sess-1</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> loadSession</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> params</span><span>:</span><span> LoadSessionRequest</span><span>)</span><span> -></span><span class="z-constant"> None</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> None</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> authenticate</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> params</span><span>:</span><span> AuthenticateRequest</span><span>)</span><span> -></span><span class="z-constant"> None</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> None</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> prompt</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> params</span><span>:</span><span> PromptRequest</span><span>)</span><span> -></span><span> PromptResponse</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> PromptResponse</span><span>(</span><span class="z-variable">stopReason</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">end_turn</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> cancel</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> params</span><span>:</span><span> CancelNotification</span><span>)</span><span> -></span><span class="z-constant"> None</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> None</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> main</span><span>(</span><span>)</span><span> -></span><span class="z-constant"> None</span><span>:</span></span>
<span class="giallo-l"><span> reader</span><span>,</span><span> writer</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span> stdio_streams</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span> AgentSideConnection</span><span>(</span><span class="z-storage z-type">lambda</span><span class="z-variable z-parameter z-function"> _conn</span><span>:</span><span> EchoAgent</span><span>(</span><span>)</span><span>,</span><span> writer</span><span>,</span><span> reader</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> await</span><span> asyncio</span><span>.</span><span>Event</span><span>(</span><span>)</span><span>.</span><span>wait</span><span>(</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">if</span><span class="z-support z-variable"> __name__</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">__main__</span><span class="z-punctuation z-definition z-string">"</span><span>:</span></span>
<span class="giallo-l"><span> asyncio</span><span>.</span><span>run</span><span>(</span><span>main</span><span>(</span><span>)</span><span>)</span></span></code></pre>
<p>Zed 侧 <code>settings.json</code>：</p>
<pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span>
<span class="giallo-l"><span class="z-support"> "</span><span class="z-support">agent_servers</span><span class="z-support">"</span><span>:</span><span> {</span></span>
<span class="giallo-l"><span class="z-support"> "</span><span class="z-support">Echo Agent (Python)</span><span class="z-support">"</span><span>:</span><span> {</span></span>
<span class="giallo-l"><span class="z-support"> "</span><span class="z-support">command</span><span class="z-support">"</span><span>:</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">/abs/path/to/python</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span class="z-support"> "</span><span class="z-support">args</span><span class="z-support">"</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">/abs/path/to/echo_agent.py</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>,</span></span>
<span class="giallo-l"><span class="z-support"> "</span><span class="z-support">env</span><span class="z-support">"</span><span>:</span><span> {</span><span>}</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span>}</span></span></code></pre>
<p>打开命令面板输入 “dev: open acp logs” 可以调试序列化。</p>
<h2 id="jie-xia-lai">接下来<a class="zola-anchor" href="#jie-xia-lai" aria-label="Anchor link for: jie-xia-lai" style="visibility: hidden;"></a>
</h2>
<ul>
<li>补充更多示例：工具调用、文件交互、计划同步；</li>
<li>与 MCP 结合，做端到端 demo；</li>
<li>观察协议演进，及时跟进 schema 变更。</li>
</ul>
<p>ACP 代表的是“交互语义的标准化”。当智能体要进主流工作流时，拥有统一契约就像当年云原生时代的容器、服务网格一样重要。Python SDK 的目标，就是让这件事变得简单，让反馈闭环先跑起来，再慢慢打磨。</p>
Agent 没有秘密可言
2025-08-14T00:00:00+00:00
2025-08-14T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/agent-has-no-secret/
<blockquote>
<p>我是 PsiACE。最近我的工作主要围绕 Agent 与 RAG 展开：<strong>少谈玄学，多把闭环跑通</strong>，多让系统说得清楚、跑得稳定、可被回放与切换。</p>
</blockquote>
<h2 id="tl-dr">TL;DR<a class="zola-anchor" href="#tl-dr" aria-label="Anchor link for: tl-dr" style="visibility: hidden;"></a>
</h2>
<ul>
<li><strong>Agent 不是新宗教</strong>。它依然是事件、队列、CRUD 的工程实践，再加一层模型协作。</li>
<li>共用一条 EventBus，把 <code>agent.*</code> 与 <code>huey.*</code> 事件打通；每条事件立即打印；最后用 Cascade 树复盘因果与时间。</li>
<li><strong>单文件 Demo，打开即跑</strong>：先看事件，后看因果，最后看结果。</li>
</ul>
<p><img src="https://psiace.me/zh/posts/agent-has-no-secret/cascade-viewer.png" alt="Cascade Viewer" /></p>
<hr />
<h2 id="wei-shen-me-xie-zhe-ge-yi-ji-wei-shen-me-zhe-me-xie">为什么写这个（以及为什么这么写）<a class="zola-anchor" href="#wei-shen-me-xie-zhe-ge-yi-ji-wei-shen-me-zhe-me-xie" aria-label="Anchor link for: wei-shen-me-xie-zhe-ge-yi-ji-wei-shen-me-zhe-me-xie" style="visibility: hidden;"></a>
</h2>
<ul>
<li>我不想再讨论"如何画出一个复杂的 Agent 架构图"。我更关心"<strong>如何让系统解释得清楚、失败得优雅、复盘得明白</strong>"。</li>
<li>这篇文章附带一个单文件 Demo：共享总线、严格 ReACT、因果与时间合并呈现、即时可观测。<strong>开箱即用</strong>。</li>
</ul>
<h2 id="wo-zen-me-zuo-de">我怎么做的<a class="zola-anchor" href="#wo-zen-me-zuo-de" aria-label="Anchor link for: wo-zen-me-zuo-de" style="visibility: hidden;"></a>
</h2>
<h3 id="he-xin-she-ji-yuan-ze">核心设计原则<a class="zola-anchor" href="#he-xin-she-ji-yuan-ze" aria-label="Anchor link for: he-xin-she-ji-yuan-ze" style="visibility: hidden;"></a>
</h3>
<ul>
<li><strong>共享 EventBus</strong>：Agent、ToolExecutor、Storage 都向同一条总线发事件。</li>
<li><strong>严格 ReACT</strong>：Thought → Action → Action Input → Observation → Final Answer。</li>
<li><strong>因果 + 时间</strong>：每轮用户输入推进 <code>tick</code>；每次 Observation 再推进 <code>tick</code>；<code>Action → huey.* → Observation</code> 通过 parent-child 串起来。</li>
<li><strong>即时可观测</strong>：每条事件实时打印；最后用树形 Cascade Viewer 做分时复盘。</li>
</ul>
<h3 id="shi-jian-liu-gai-lan">事件流（概览）<a class="zola-anchor" href="#shi-jian-liu-gai-lan" aria-label="Anchor link for: shi-jian-liu-gai-lan" style="visibility: hidden;"></a>
</h3>
<p><img src="https://psiace.me/zh/posts/agent-has-no-secret/cascade-viewer.png" alt="The Agent Loop" /></p>
<h2 id="zhe-he-chuan-tong-jia-gou-you-shen-me-bu-tong">这和"传统架构"有什么不同？<a class="zola-anchor" href="#zhe-he-chuan-tong-jia-gou-you-shen-me-bu-tong" aria-label="Anchor link for: zhe-he-chuan-tong-jia-gou-you-shen-me-bu-tong" style="visibility: hidden;"></a>
</h2>
<ul>
<li><strong>没有不同</strong>：事件、队列、CRUD，本来就在；只是把模型作为协作者接了进来。</li>
<li><strong>也不浮夸</strong>：没有"智能"也不会失效的设计；它可靠、可解释，也更容易落地。</li>
</ul>
<h2 id="ji-jian-gu-jia-jie-xuan">极简骨架（节选）<a class="zola-anchor" href="#ji-jian-gu-jia-jie-xuan" aria-label="Anchor link for: ji-jian-gu-jia-jie-xuan" style="visibility: hidden;"></a>
</h2>
<h3 id="event-driven-storage-wrapper">Event-driven storage wrapper<a class="zola-anchor" href="#event-driven-storage-wrapper" aria-label="Anchor link for: event-driven-storage-wrapper" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> EventureMemoryStorage</span><span>(</span><span class="z-entity">MemoryStorage</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-support"> __init__</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> event_bus</span><span>:</span><span> EventBus</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-support"> super</span><span>(</span><span>)</span><span>.</span><span class="z-support">__init__</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">huey</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>bus</span><span class="z-keyword"> =</span><span> event_bus</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> enqueue</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> data</span><span>,</span><span class="z-variable z-parameter z-function"> priority</span><span class="z-keyword">=</span><span class="z-constant">None</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-support"> super</span><span>(</span><span>)</span><span>.</span><span>enqueue</span><span>(</span><span>data</span><span>,</span><span class="z-variable"> priority</span><span class="z-keyword">=</span><span>priority</span><span>)</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>bus</span><span>.</span><span>publish</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">huey.queue.enqueue</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">data</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span> data</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">priority</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span> priority</span></span>
<span class="giallo-l"><span> }</span><span>)</span></span></code></pre><h3 id="tool-with-self-description">Tool with self-description<a class="zola-anchor" href="#tool-with-self-description" aria-label="Anchor link for: tool-with-self-description" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> tool_echo</span><span>(</span><span class="z-variable z-parameter z-function">params</span><span>:</span><span class="z-support"> dict</span><span>)</span><span> -></span><span class="z-support"> dict</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span><span class="z-string">Echo back text. Args: {"text": string} Returns: {"ok": bool, "echo": string}</span><span class="z-punctuation z-definition z-string">"""</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> {</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">ok</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-constant"> True</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">echo</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-support"> str</span><span>(</span><span>params</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">text</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>)</span><span>}</span></span></code></pre><h3 id="react-loop-he-xin-si-xiang">ReACT loop（核心思想）<a class="zola-anchor" href="#react-loop-he-xin-si-xiang" aria-label="Anchor link for: react-loop-he-xin-si-xiang" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">while</span><span class="z-constant"> True</span><span>:</span></span>
<span class="giallo-l"><span> resp</span><span class="z-keyword"> =</span><span> client</span><span>.</span><span>chat</span><span>.</span><span>completions</span><span>.</span><span>create</span><span>(</span><span class="z-variable">model</span><span class="z-keyword">=</span><span>model</span><span>,</span><span class="z-variable"> messages</span><span class="z-keyword">=</span><span>history</span><span>)</span></span>
<span class="giallo-l"><span> assistant</span><span class="z-keyword"> =</span><span> resp</span><span>.</span><span>choices</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>message</span><span>.</span><span>content</span><span class="z-keyword"> or</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"><span> call</span><span class="z-keyword"> =</span><span> extract</span><span>(</span><span>assistant</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> call</span><span>:</span></span>
<span class="giallo-l"><span> action_id</span><span class="z-keyword"> =</span><span> uuid4</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span> bus</span><span>.</span><span>publish</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">agent.action</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span> {</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">id</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span> action_id</span><span>,</span><span class="z-keyword"> **</span><span>call</span><span>}</span><span>)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> wait for agent.observation(id==action_id) and append as Observation</span></span>
<span class="giallo-l"><span class="z-keyword"> continue</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> assistant</span></span></code></pre><h2 id="wo-zun-xun-de-ji-ge-yuan-ze">我遵循的几个原则<a class="zola-anchor" href="#wo-zun-xun-de-ji-ge-yuan-ze" aria-label="Anchor link for: wo-zun-xun-de-ji-ge-yuan-ze" style="visibility: hidden;"></a>
</h2>
<ul>
<li><strong>先闭环，后花活</strong>：先把"事件→队列→状态变化→ReACT"打通，再谈优化。</li>
<li><strong>因果与时间是工程的一等公民</strong>：tick 表达更新周期；parent-child 表达触发链。</li>
<li><strong>可观测性优先</strong>：当系统能解释自己，优化才有基础。</li>
<li><strong>可替换</strong>：总线稳定，后端可换（内存→Redis），模型可换（供应商/版本）。</li>
</ul>
<h2 id="ru-he-yun-xing-dan-zhong-duan">如何运行（单终端）<a class="zola-anchor" href="#ru-he-yun-xing-dan-zhong-duan" aria-label="Anchor link for: ru-he-yun-xing-dan-zhong-duan" style="visibility: hidden;"></a>
</h2>
<h3 id="dai-ma-wei-zhi">代码位置<a class="zola-anchor" href="#dai-ma-wei-zhi" aria-label="Anchor link for: dai-ma-wei-zhi" style="visibility: hidden;"></a>
</h3>
<p>请点击【阅读原文】跳转：</p>
<ul>
<li><a rel="nofollow noreferrer external" href="https://github.com/PsiACE/psiace/blob/main/demo/agent-has-no-secret/agent_has_no_secret.py">agent_has_no_secret.py</a></li>
<li><a rel="nofollow noreferrer external" href="https://github.com/PsiACE/psiace/blob/main/demo/agent-has-no-secret/README.md">README.md</a></li>
</ul>
<h3 id="yun-xing-bu-zou">运行步骤<a class="zola-anchor" href="#yun-xing-bu-zou" aria-label="Anchor link for: yun-xing-bu-zou" style="visibility: hidden;"></a>
</h3>
<ol>
<li>配置 <code>.env</code>（OpenRouter 推荐；OpenAI 也可）</li>
<li><code>python agent_has_no_secret.py</code></li>
</ol>
<h3 id="ni-jiang-kan-dao-shen-me">你将看到什么<a class="zola-anchor" href="#ni-jiang-kan-dao-shen-me" aria-label="Anchor link for: ni-jiang-kan-dao-shen-me" style="visibility: hidden;"></a>
</h3>
<ul>
<li><strong>实时事件流</strong>：<code>user.input</code>、<code>agent.thought</code>、<code>agent.action</code>、<code>huey.data.*</code>、<code>agent.observation</code> …</li>
<li>绿色的 <strong>Final Answer</strong> 面板</li>
<li>按 tick 分组的<strong>树形 Cascade Viewer</strong>：在 <code>agent.action</code> 下能看到 <code>huey.data.*</code> 与 <code>agent.observation</code> 的父子层级</li>
</ul>
<hr />
<h2 id="xie-zai-zui-hou">写在最后<a class="zola-anchor" href="#xie-zai-zui-hou" aria-label="Anchor link for: xie-zai-zui-hou" style="visibility: hidden;"></a>
</h2>
<p>我更钦佩能把东西"<strong>说清楚、跑起来</strong>"的工程师。Agent 没有秘密可言：</p>
<ul>
<li>先把闭环打通，再考虑花活；</li>
<li>先让因果与代价可见，再谈"更聪明"。</li>
</ul>
Baby Steps: 用 Python 实现一个能自举的 Coding Agent
2025-07-16T00:00:00+00:00
2025-07-16T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/baby-step-coding-agent/
<p>Bub 的第一个 milestone：自动修类型注解。由 Moonshot K2 驱动</p>
<blockquote>
<p><strong>Bub:</strong> Successfully fixed the first mypy issue by adding the missing return type annotation <code>-> None</code> to the <code>__init__</code> method in <code>src/bub/cli/render.py</code>, reducing the error count from 24 to 23.</p>
</blockquote>
<h2 id="1-wei-shen-me-yao-zi-ji-zao-agent">1. 为什么要自己造 Agent？<a class="zola-anchor" href="#1-wei-shen-me-yao-zi-ji-zao-agent" aria-label="Anchor link for: 1-wei-shen-me-yao-zi-ji-zao-agent" style="visibility: hidden;"></a>
</h2>
<p>Coding Agent 现在已经是个红海赛道，市面上有不少优秀的产品，比如 yetone 的 avante.nvim、晋涛哥哥推荐的 AmpCode，还有许多团队在 PPT 中绘制宏伟蓝图。然而，Coding Agent 的“token 大力出奇迹”现象也很明显——动辄几十万 token 的消耗，真正有价值的部分却少之又少。这让我很好奇：如果自己动手造一个 Coding Agent，能不能找到更高效、更实用的解决方案？</p>
<p>于是，我开始折腾一个叫 Bub 的 CLI 助手。它的目标很简单：做一个命令行下的实用助手，同时具备有限的自举能力。自举这个概念在编译器、操作系统领域早已不算新鲜，很多 Coding Agent 也喜欢宣传“AI 工程师贡献了多少代码”。我希望 Bub 能迈出自己的第一步，解决它自身代码中的第一个实际问题。</p>
<hr />
<h2 id="2-zui-xiao-ke-yong-xian-pao-qi-lai-zai-shuo">2. 最小可用：先跑起来再说<a class="zola-anchor" href="#2-zui-xiao-ke-yong-xian-pao-qi-lai-zai-shuo" aria-label="Anchor link for: 2-zui-xiao-ke-yong-xian-pao-qi-lai-zai-shuo" style="visibility: hidden;"></a>
</h2>
<p>我的经验是，能跑起来的最小闭环最重要，别一上来就追求“完美架构”或者花太多时间做数据小偷。</p>
<p>Bub 的分层很简单：</p>
<ul>
<li><strong>Agent</strong>：主循环，负责 LLM 交互、工具调用、上下文管理。</li>
<li><strong>Tool</strong>：每个工具一个类，参数用 Pydantic 校验。</li>
<li><strong>ToolRegistry</strong>：注册所有工具，方便扩展。</li>
<li><strong>CLI</strong>：Typer + Rich，命令行入口，支持展开中间状态。</li>
</ul>
<p>Agent 的本质其实就是一个 while 循环。每次循环，Agent 会根据当前上下文判断是否需要调用工具，如果需要就调用，然后把工具的返回结果写回上下文。</p>
<h3 id="zhu-xun-huan-he-xin-dai-ma">主循环核心代码<a class="zola-anchor" href="#zhu-xun-huan-he-xin-dai-ma" aria-label="Anchor link for: zhu-xun-huan-he-xin-dai-ma" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> Agent</span><span>:</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> chat</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> message</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -></span><span class="z-support"> str</span><span>:</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>conversation_history</span><span>.</span><span>append</span><span>(</span><span>Message</span><span>(</span><span class="z-variable">role</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">user</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> content</span><span class="z-keyword">=</span><span>message</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> while</span><span class="z-constant"> True</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 构造上下文，历史消息+工具列表</span></span>
<span class="giallo-l"><span class="z-constant"> ...</span></span>
<span class="giallo-l"><span> response</span><span class="z-keyword"> =</span><span> litellm</span><span>.</span><span>completion</span><span>(</span><span class="z-constant">...</span><span>)</span></span>
<span class="giallo-l"><span> assistant_message</span><span class="z-keyword"> =</span><span class="z-support"> str</span><span>(</span><span>response</span><span>.</span><span>choices</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>message</span><span>.</span><span>content</span><span>)</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>conversation_history</span><span>.</span><span>append</span><span>(</span><span>Message</span><span>(</span><span class="z-variable">role</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">assistant</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> content</span><span class="z-keyword">=</span><span>assistant_message</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span> tool_calls</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>tool_executor</span><span>.</span><span>extract_tool_calls</span><span>(</span><span>assistant_message</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> tool_calls</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> for</span><span> tool_call</span><span class="z-keyword"> in</span><span> tool_calls</span><span>:</span></span>
<span class="giallo-l"><span> result</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>tool_executor</span><span>.</span><span>execute_tool</span><span>(</span><span>tool_call</span><span>.</span><span>name</span><span>,</span><span class="z-keyword"> **</span><span>tool_call</span><span>.</span><span>parameters</span><span>)</span></span>
<span class="giallo-l"><span> observation</span><span class="z-keyword"> =</span><span class="z-storage z-type"> f</span><span class="z-string">"</span><span class="z-string">Observation: </span><span class="z-constant">{</span><span>result</span><span>.</span><span>format_result</span><span>(</span><span>)</span><span class="z-constant">}</span><span class="z-string">"</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>conversation_history</span><span>.</span><span>append</span><span>(</span><span>Message</span><span>(</span><span class="z-variable">role</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">user</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> content</span><span class="z-keyword">=</span><span>observation</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> continue</span></span>
<span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> assistant_message</span></span></code></pre>
<p><strong>踩过的坑：</strong></p>
<ul>
<li>没有捕获，LLM 输出格式一变就死循环</li>
<li>工具参数没校验，LLM 乱传参数直接崩</li>
<li>Observation 反馈太长或缺乏有效信息，LLM 理解困难</li>
</ul>
<hr />
<h2 id="3-gong-ju-ding-yi-kuo-zhan-llm-de-neng-li">3. 工具定义：扩展 LLM 的能力<a class="zola-anchor" href="#3-gong-ju-ding-yi-kuo-zhan-llm-de-neng-li" aria-label="Anchor link for: 3-gong-ju-ding-yi-kuo-zhan-llm-de-neng-li" style="visibility: hidden;"></a>
</h2>
<p>工具是 LLM 和外部世界的桥梁，定义得好，模型才能真正“动手”。我的做法是：</p>
<ul>
<li>工具参数全部用 Pydantic 校验，类型不对直接拒绝。</li>
<li>命令行工具有黑名单（比如 <code>rm</code>、<code>del</code>），遇到危险命令直接报错。</li>
<li>工具执行结果结构化返回，别让 LLM 猜。</li>
<li>操作命令行工具时，stdout 和 stderr 都很重要，不能只给 exit code。</li>
<li>工具之间要有明确边界，避免混淆。</li>
</ul>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> RunCommandTool</span><span>(</span><span class="z-entity">Tool</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-constant"> DANGEROUS_COMMANDS</span><span class="z-keyword"> =</span><span> {</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">rm</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">del</span><span class="z-punctuation z-definition z-string">"</span><span>}</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> _validate_command</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> base_cmd</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -></span><span> Optional</span><span>[</span><span class="z-support">str</span><span>]</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> base_cmd</span><span class="z-keyword"> in</span><span class="z-variable z-language"> self</span><span>.</span><span class="z-constant">DANGEROUS_COMMANDS</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> f</span><span class="z-string">"</span><span class="z-string">Dangerous command blocked: </span><span class="z-constant">{</span><span>base_cmd</span><span class="z-constant">}</span><span class="z-string">"</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> execute</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> context</span><span>:</span><span> Context</span><span>)</span><span> -></span><span> ToolResult</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 校验命令，执行并返回结果</span></span></code></pre>
<hr />
<h2 id="4-prompt-she-ji-rang-llm-an-tao-lu-chu-pai">4. Prompt 设计：让 LLM 按套路出牌<a class="zola-anchor" href="#4-prompt-she-ji-rang-llm-an-tao-lu-chu-pai" aria-label="Anchor link for: 4-prompt-she-ji-rang-llm-an-tao-lu-chu-pai" style="visibility: hidden;"></a>
</h2>
<p>组织良好的提示词能显著提升 LLM 的输出质量。对于 Coding Agent 来说尤其重要，因为 LLM 的输出格式很容易失控。</p>
<p>我的经验：</p>
<ul>
<li>Prompt 里要列出所有工具和参数 schema。</li>
<li>多给几个调用示例，覆盖常见用法。</li>
<li>Observation 反馈要简洁，别堆无用信息。</li>
</ul>
<p><strong>Bub 的 ReAct Prompt 结构：</strong></p>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>You are an AI assistant with access to tools. When you need to use a tool, follow this format:</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>Thought: ...</span></span>
<span class="giallo-l"><span>Action: run_command</span></span>
<span class="giallo-l"><span>Action Input: {"command": "ls"}</span></span>
<span class="giallo-l"><span>Observation: <output></span></span>
<span class="giallo-l"><span>...</span></span>
<span class="giallo-l"><span>Final Answer: <your answer></span></span></code></pre>
<p>ReAct 的好处是简单直接，容易落地，虽然 token 消耗大，但能快速试错、跨模型迁移。</p>
<hr />
<h2 id="5-milestone-zi-dong-xiu-lei-xing-zhu-jie">5. milestone：自动修类型注解<a class="zola-anchor" href="#5-milestone-zi-dong-xiu-lei-xing-zhu-jie" aria-label="Anchor link for: 5-milestone-zi-dong-xiu-lei-xing-zhu-jie" style="visibility: hidden;"></a>
</h2>
<p>定义好 Agent Loop、工具和 Prompt 后，Bub 的第一个 milestone 就是自动修复了一个 mypy 报错。</p>
<p>比如：</p>
<pre class="giallo z-code"><code data-lang="diff"><span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> def __init__(self):</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self.console = Console()</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self._show_debug = False</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> def __init__(self) -> None:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.console: Console = Console()</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self._show_debug: bool = False</span></span></code></pre>
<p>实际的 Agent Loop：</p>
<ul>
<li>只让 agent 改类型注解、格式化、重命名，别让它碰复杂逻辑。</li>
<li>先用命令行工具执行 <code>mypy</code>，拿到报错信息。</li>
<li>让 agent 生成修复建议，再用 file edit 工具应用到代码。</li>
<li>修完自动再跑一次 mypy，确保没新问题。</li>
</ul>
<p><strong>踩过的坑：</strong></p>
<ul>
<li>模型对代码上下文理解有限，经常修错。</li>
<li>不验证，bug 越修越多。</li>
</ul>
<hr />
<h2 id="6-jin-jie-wan-fa-yu-gong-cheng-zi-cha">6. 进阶玩法与工程自查<a class="zola-anchor" href="#6-jin-jie-wan-fa-yu-gong-cheng-zi-cha" aria-label="Anchor link for: 6-jin-jie-wan-fa-yu-gong-cheng-zi-cha" style="visibility: hidden;"></a>
</h2>
<p>随着功能扩展，踩的坑也越来越多。我的一些经验：</p>
<ul>
<li>工具扩展时，建议单一职责，参数 schema 明确。</li>
<li>长对话要截断或摘要，别让 LLM 超窗。</li>
<li>生产环境建议沙箱/虚拟机，命令行工具默认禁危险命令。</li>
<li>LLM 输出格式不稳时要有 fallback 兜底。</li>
</ul>
<h2 id="7-zong-jie">7. 总结<a class="zola-anchor" href="#7-zong-jie" aria-label="Anchor link for: 7-zong-jie" style="visibility: hidden;"></a>
</h2>
<p>Bub 还在早期，但已经能帮我自动修 bug、跑命令、读写文件。我希望这只是一个开始，然后得到更多有意思的反馈。</p>
<p><img src="https://psiace.me/zh/posts/baby-step-coding-agent/bub-it.jpeg" alt="Bub it. Build.it" /></p>
<hr />
<h3 id="can-kao-zi-liao">参考资料<a class="zola-anchor" href="#can-kao-zi-liao" aria-label="Anchor link for: can-kao-zi-liao" style="visibility: hidden;"></a>
</h3>
<ul>
<li><a rel="nofollow noreferrer external" href="https://ampcode.com/how-to-build-an-agent">How to Build an Agent (ampcode)</a></li>
<li><a rel="nofollow noreferrer external" href="https://huggingface.co/blog/tiny-agents">Tiny Agents: Building LLM-Powered Agents from Scratch (HuggingFace)</a></li>
<li><a rel="nofollow noreferrer external" href="https://github.com/PsiACE/bub">Bub: Bub it. Build it.</a></li>
</ul>
让 LlamaIndex 接上 Cloudflare AI Gateway
2025-07-11T00:00:00+00:00
2025-07-11T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/llama-index-cloudflare-ai-gateway/
<h2 id="wei-shen-me-zhe-teng-zhe-ge">为什么折腾这个<a class="zola-anchor" href="#wei-shen-me-zhe-teng-zhe-ge" aria-label="Anchor link for: wei-shen-me-zhe-teng-zhe-ge" style="visibility: hidden;"></a>
</h2>
<p>单供应商的 LLM 太脆弱：OpenAI 宕机、Anthropic 限流，就等于业务停摆。Cloudflare AI Gateway 给了一个诱人的承诺：</p>
<ul>
<li>多家模型的统一入口；</li>
<li>内置缓存、限流、熔断；</li>
<li>请求失败自动切换。</li>
</ul>
<p>问题是，LlamaIndex 的 LLM 调用直接命中各家 API，没法自适应 Gateway。我需要一个中间层，让原有代码不改，直接享受多云编排。</p>
<h2 id="jie-jue-fang-an">解决方案<a class="zola-anchor" href="#jie-jue-fang-an" aria-label="Anchor link for: jie-jue-fang-an" style="visibility: hidden;"></a>
</h2>
<p>写了一个轻量 wrapper：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>llms</span><span>.</span><span>cloudflare_ai_gateway</span><span class="z-keyword"> import</span><span> CloudflareAIGateway</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>llms</span><span>.</span><span>openai</span><span class="z-keyword"> import</span><span> OpenAI</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>llms</span><span>.</span><span>anthropic</span><span class="z-keyword"> import</span><span> Anthropic</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>openai_llm</span><span class="z-keyword"> =</span><span> OpenAI</span><span>(</span><span class="z-variable">model</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">gpt-4o-mini</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> api_key</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">your-key</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span>anthropic_llm</span><span class="z-keyword"> =</span><span> Anthropic</span><span>(</span><span class="z-variable">model</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">claude-3-5-sonnet</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> api_key</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">your-key</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>gateway_llm</span><span class="z-keyword"> =</span><span> CloudflareAIGateway</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> llms</span><span class="z-keyword">=</span><span>[</span><span>openai_llm</span><span>,</span><span> anthropic_llm</span><span>]</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> account_id</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">your-cloudflare-account-id</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> gateway</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">your-gateway-name</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> api_key</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">your-cloudflare-api-key</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>resp</span><span class="z-keyword"> =</span><span> gateway_llm</span><span>.</span><span>chat</span><span>(</span><span>[</span><span>ChatMessage</span><span>(</span><span class="z-variable">role</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">user</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> content</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">2 + 2 = ?</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>]</span><span>)</span></span></code></pre>
<p>作用就是：截住 LlamaIndex 发出的请求，改写为 Cloudflare 期待的格式，处理返回值。原始业务代码不用动。</p>
<h2 id="neng-zuo-shen-me">能做什么<a class="zola-anchor" href="#neng-zuo-shen-me" aria-label="Anchor link for: neng-zuo-shen-me" style="visibility: hidden;"></a>
</h2>
<ul>
<li>顺序尝试多个模型，失败自动换下一个；</li>
<li>支持 Cloudflare 的流式接口、异步调用；</li>
<li>统一注入鉴权、重试、日志；</li>
<li>经过实测的模型：OpenAI、Anthropic；</li>
<li>理论兼容：Google AI Studio、DeepSeek、Grok、Azure OpenAI、Perplexity、Replicate 等。</li>
</ul>
<h2 id="ru-he-ti-yan">如何体验<a class="zola-anchor" href="#ru-he-ti-yan" aria-label="Anchor link for: ru-he-ti-yan" style="visibility: hidden;"></a>
</h2>
<p>PR 在提审（<a rel="nofollow noreferrer external" href="https://github.com/run-llama/llama_index/pull/19395">#19395</a>），不过代码已经能跑：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">git</span><span class="z-string"> clone</span><span class="z-keyword"> <</span><span class="z-string">rep</span><span>o</span><span class="z-keyword">></span></span>
<span class="giallo-l"><span class="z-support">cd</span><span class="z-string"> llama-index-llms-cloudflare-ai-gateway</span></span>
<span class="giallo-l"><span class="z-entity z-name">pip</span><span class="z-string"> install</span><span class="z-constant"> -</span><span class="z-constant">e</span><span class="z-string"> .</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage">export</span><span class="z-variable z-other"> OPENAI_API_KEY</span><span class="z-keyword">=</span><span>...</span></span>
<span class="giallo-l"><span class="z-storage">export</span><span class="z-variable z-other"> ANTHROPIC_API_KEY</span><span class="z-keyword">=</span><span>...</span></span>
<span class="giallo-l"><span class="z-storage">export</span><span class="z-variable z-other"> CLOUDFLARE_ACCOUNT_ID</span><span class="z-keyword">=</span><span>...</span></span>
<span class="giallo-l"><span class="z-storage">export</span><span class="z-variable z-other"> CLOUDFLARE_API_KEY</span><span class="z-keyword">=</span><span>...</span></span>
<span class="giallo-l"><span class="z-storage">export</span><span class="z-variable z-other"> CLOUDFLARE_GATEWAY</span><span class="z-keyword">=</span><span>...</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name">uv</span><span class="z-string"> run</span><span class="z-string"> pytest</span><span class="z-string"> tests/</span></span></code></pre><h2 id="zhu-yi-shi-xiang">注意事项<a class="zola-anchor" href="#zhu-yi-shi-xiang" aria-label="Anchor link for: zhu-yi-shi-xiang" style="visibility: hidden;"></a>
</h2>
<ul>
<li>Cloudflare 虽然提供 OpenAI 兼容接口，但做中间层能解锁更多功能（自定义头、特定路由、日志追踪）。</li>
<li>多模型编排别忘了考虑一致性：模型切换后回答风格可能不同，需要在应用层消化。</li>
<li>缓存命中率很依赖 prompt 规范，必要时结合 embedding 去重。</li>
</ul>
<p>这个封装的意义不在于“又造了个轮子”，而是告诉你：在 LlamaIndex 体系里，替换底层 LLM 客户端是很容易的。运维侧想要多云容灾、成本优化，只需要写一个薄薄的适配层。</p>
用 WebAssembly 为 Code Agent 范式构建安全沙箱
2025-07-08T00:00:00+00:00
2025-07-08T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/wasmtime-executor-for-code-agents/
<p>Code Agent（代码代理范式）的能力令人惊叹，但安全性问题同样令人担忧。在我测试第一个 Code Agent 时，它很快就尝试安装包、访问环境变量，甚至想要读取系统文件。<strong>我们需要一个真正安全的执行环境。</strong></p>
<h2 id="an-quan-tiao-zhan">安全挑战<a class="zola-anchor" href="#an-quan-tiao-zhan" aria-label="Anchor link for: an-quan-tiao-zhan" style="visibility: hidden;"></a>
</h2>
<p>代码执行型 AI 代理（Code Agent 范式）确实能完成很多任务——数据分析、数学计算、代码调试。但它们缺乏对系统边界的认知，可能带来严重的安全风险。</p>
<p>典型的安全威胁场景：</p>
<ul>
<li><strong>权限越界</strong>：尝试访问 <code>/etc/passwd</code>、系统环境变量</li>
<li><strong>恶意包安装</strong>：从被污染的 PyPI 源安装恶意包</li>
<li><strong>资源耗尽</strong>：无限循环、内存泄漏导致系统崩溃</li>
<li><strong>网络攻击</strong>：发起 DDoS、端口扫描等恶意行为</li>
</ul>
<p>像 <a rel="nofollow noreferrer external" href="https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py">Hugging Face smolagents</a> 之类的项目已经意识到了这个问题，提供了多种执行器选项来平衡功能性和安全性。</p>
<h2 id="webassembly-de-an-quan-you-shi">WebAssembly 的安全优势<a class="zola-anchor" href="#webassembly-de-an-quan-you-shi" aria-label="Anchor link for: webassembly-de-an-quan-you-shi" style="visibility: hidden;"></a>
</h2>
<p>WebAssembly 的核心价值不在于性能，而在于<strong>原生安全设计</strong>。作为从浏览器安全模型发展而来的技术，WASM 提供了：</p>
<ol>
<li><strong>能力安全模型</strong>：基于最小权限原则，只能访问明确授权的资源</li>
<li><strong>细粒度资源控制</strong>：精确监控 CPU 使用、内存分配、网络访问</li>
<li><strong>执行确定性</strong>：相同的输入总是产生相同的输出，便于审计</li>
<li><strong>语言无关性</strong>：支持多种编程语言的安全执行</li>
</ol>
<p>Simon Willison 在他的 <a rel="nofollow noreferrer external" href="https://til.simonwillison.net/webassembly/python-in-a-wasm-sandbox">TIL 文章</a> 中详细探讨了这个方案，<a rel="nofollow noreferrer external" href="https://news.ycombinator.com/item?id=34581487">Hacker News 社区也有深入讨论</a>。</p>
<p>虽然 <a rel="nofollow noreferrer external" href="https://github.com/huggingface/smolagents">Hugging Face smolagents</a> 已经提供了基于 Pyodide 和 Deno 的 <code>WasmExecutor</code>，但我想探索一个基于 wasmtime 的本地执行方案，看看有什么不同的技术权衡。</p>
<h2 id="ji-shu-shi-xian">技术实现<a class="zola-anchor" href="#ji-shu-shi-xian" aria-label="Anchor link for: ji-shu-shi-xian" style="visibility: hidden;"></a>
</h2>
<p>基于 wasmtime-py 和 VMware 的 Python WASM 运行时，我实现了一个简单的沙箱执行器：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> wasmtime_executor</span><span class="z-keyword"> import</span><span> WasmtimePythonExecutor</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> smolagents</span><span class="z-keyword"> import</span><span> CodeAgent</span><span>,</span><span> InferenceClientModel</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> WasmtimeCodeAgent</span><span>(</span><span class="z-entity">CodeAgent</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> create_python_executor</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> WasmtimePythonExecutor</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> additional_authorized_imports</span><span class="z-keyword">=</span><span class="z-variable z-language">self</span><span>.</span><span>additional_authorized_imports</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> max_print_outputs_length</span><span class="z-keyword">=</span><span class="z-variable z-language">self</span><span>.</span><span>max_print_outputs_length</span><span>,</span></span>
<span class="giallo-l"><span class="z-keyword"> **</span><span class="z-variable z-language">self</span><span>.</span><span>executor_kwargs</span><span>,</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>agent</span><span class="z-keyword"> =</span><span> WasmtimeCodeAgent</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> tools</span><span class="z-keyword">=</span><span>[</span><span>]</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> model</span><span class="z-keyword">=</span><span>InferenceClientModel</span><span>(</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> additional_authorized_imports</span><span class="z-keyword">=</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">math</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">json</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>,</span></span>
<span class="giallo-l"><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>result</span><span class="z-keyword"> =</span><span> agent</span><span>.</span><span>run</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Calculate the square root of 125</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span></code></pre>
<p>核心实现思路：利用 VMware 提供的 Python WASM 二进制文件，通过 wasmtime-py 进行运行时管理，并实现与 smolagents 的兼容层。关键的技术差异在于<strong>本地执行</strong>，避免了对外部 Deno 运行时的依赖。</p>
<h2 id="ji-shu-ping-gu">技术评估<a class="zola-anchor" href="#ji-shu-ping-gu" aria-label="Anchor link for: ji-shu-ping-gu" style="visibility: hidden;"></a>
</h2>
<p><strong>优势方面：</strong></p>
<ul>
<li>与 smolagents 框架的无缝集成</li>
<li>基础 Python 操作的良好支持</li>
<li>完善的错误处理和异常捕获</li>
<li>执行状态的有效隔离和持久化</li>
<li><strong>本地化部署</strong>，减少网络依赖</li>
</ul>
<p><strong>技术权衡：</strong></p>
<ul>
<li>安全隔离 vs Python 生态系统限制</li>
<li>执行安全性 vs 性能开销</li>
<li>确定性执行 vs 配置复杂性</li>
<li><strong>本地控制</strong> vs 远程服务调用</li>
</ul>
<h2 id="sheng-chan-jiu-xu-xing">生产就绪性<a class="zola-anchor" href="#sheng-chan-jiu-xu-xing" aria-label="Anchor link for: sheng-chan-jiu-xu-xing" style="visibility: hidden;"></a>
</h2>
<p><strong>当前状态：实验性项目</strong>。这个实现主要用于概念验证和技术探索。</p>
<p>生产环境部署需要解决的关键问题：</p>
<ul>
<li>资源限制和配额管理</li>
<li>包依赖管理和安全扫描</li>
<li>性能优化和缓存策略</li>
<li>完整的审计日志和监控</li>
<li>安全漏洞的持续评估</li>
</ul>
<p>但对于技术研究、原型验证、理解安全边界？这个实现提供了很好的起点。</p>
<h2 id="ji-shu-jia-zhi">技术价值<a class="zola-anchor" href="#ji-shu-jia-zhi" aria-label="Anchor link for: ji-shu-jia-zhi" style="visibility: hidden;"></a>
</h2>
<p>这个项目的真正价值不在于具体的实现代码，而在于证明了<strong>Code Agent 范式存在多种安全沙箱方案</strong>。虽然 smolagents 提供了基于 Pyodide 的 Deno 沙箱，wasmtime 为本地执行提供了另一种技术选择。开发者可以基于现有的代理框架，添加安全边界，保持功能完整性，同时探索不同的技术权衡。</p>
<h2 id="jin-yi-bu-tan-suo">进一步探索<a class="zola-anchor" href="#jin-yi-bu-tan-suo" aria-label="Anchor link for: jin-yi-bu-tan-suo" style="visibility: hidden;"></a>
</h2>
<p>完整的实现代码和详细文档在我的 <a rel="nofollow noreferrer external" href="https://github.com/psiace/psiace/tree/main/demo/wasmtime-executor">Wasmtime 执行器项目</a> 中。代码虽然粗糙，但功能完整。欢迎克隆、测试、改进。</p>
<p>理解 Code Agent 范式安全挑战的最佳方式就是动手实践。即使是简单的概念验证项目，也能带来深刻的技术洞察。</p>
<hr />
<h2 id="can-kao-zi-liao">参考资料<a class="zola-anchor" href="#can-kao-zi-liao" aria-label="Anchor link for: can-kao-zi-liao" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="nofollow noreferrer external" href="https://github.com/huggingface/smolagents">Hugging Face smolagents</a></li>
<li><a rel="nofollow noreferrer external" href="https://github.com/psiace/psiace/tree/main/demo/wasmtime-executor">Wasmtime 执行器项目</a></li>
<li><a rel="nofollow noreferrer external" href="https://til.simonwillison.net/webassembly/python-in-a-wasm-sandbox">Simon Willison 的 WASM Python 沙箱</a></li>
<li><a rel="nofollow noreferrer external" href="https://github.com/vmware-labs/webassembly-language-runtimes">VMware WebAssembly 语言运行时</a></li>
</ul>
当 RAG 遇上编程助手
2025-06-18T00:00:00+00:00
2025-06-18T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/rag-in-coding-agent/
<blockquote>
<p>我的日常工作是和 RAG 打交道，最近 Coding Agent 大热，Claude Code 、Cursor 这样的工具已经成为了研发必备的效率神器，于是尝试调研和学习了一下，抛砖引玉。</p>
</blockquote>
<h2 id="tl-dr">TL;DR<a class="zola-anchor" href="#tl-dr" aria-label="Anchor link for: tl-dr" style="visibility: hidden;"></a>
</h2>
<p>Coding Agent 中其实不少环节都可以用到 RAG（检索增强生成），把"查资料"和"写代码"这两件事结合起来。具体来说：</p>
<ul>
<li><strong>理解你想干什么</strong>：分析需求，找到相关代码和文档</li>
<li><strong>快速定位文件</strong>：在大项目里找到关键模块</li>
<li><strong>写出合适的代码</strong>：基于实际情况和最佳实践</li>
<li><strong>帮你调试</strong>：分析错误，搜索解决方案</li>
</ul>
<p>说白了，就是让编程助手从"代码生成器"变成真正的"软件工程师"。</p>
<hr />
<h2 id="xie-dai-ma-de-zhen-shi-tong-dian">写代码的真实痛点<a class="zola-anchor" href="#xie-dai-ma-de-zhen-shi-tong-dian" aria-label="Anchor link for: xie-dai-ma-de-zhen-shi-tong-dian" style="visibility: hidden;"></a>
</h2>
<p>作为一个软件工程师，大部分时间我们都在干这些事：</p>
<ul>
<li>搞懂一个巨大项目是怎么工作的</li>
<li>在几百个文件里找到那个该死的模块</li>
<li>看着莫名其妙的报错发呆</li>
<li>学新框架新工具</li>
</ul>
<p><img src="https://psiace.me/zh/posts/rag-in-coding-agent/swe-bench.png" alt="SWE Benchmark" /></p>
<p>这些事情真的很烦，也很费时间。Coding Agent 应该帮我们处理这些重复劳动，让我们可以自由表达自己的想法。假如你的 “编程搭子” 还不够聪明，理解不了你的代码，找不到对的信息，那几乎只会搞砸一切，更别说帮你调试了。</p>
<hr />
<h2 id="coding-agent-dao-di-shi-shen-me">Coding Agent 到底是什么<a class="zola-anchor" href="#coding-agent-dao-di-shi-shen-me" aria-label="Anchor link for: coding-agent-dao-di-shi-shen-me" style="visibility: hidden;"></a>
</h2>
<p>想象一下，你要做一个从没做过的功能。通常你会这样：</p>
<ul>
<li>先 Google 找例子</li>
<li>翻框架文档</li>
<li>在自己项目里搜类似的代码</li>
<li>上 StackOverflow 看看别人怎么解决的</li>
</ul>
<p>Coding Agent 就是一个可以自主执行这些动作的智能体，或者说把这个过程自动化了。它不仅可以充当搜索引擎进行学习，还能把找到的信息组合起来，帮你写代码。</p>
<p>原理其实很简单：</p>
<ol>
<li><strong>检索（Retrieval）</strong>：找相关的东西——代码、文档、问答</li>
<li><strong>生成（Generation）</strong>：用这些信息写出新的代码或解决方案</li>
</ol>
<p>就这两步，但效果比单纯的代码生成器强多了。</p>
<blockquote>
<p>当然，为了让一切更加顺利，还需要添加反馈机制。根据调试信息优化并进行修正。</p>
</blockquote>
<hr />
<h2 id="rag-zen-me-rang-bian-cheng-zhu-shou-bian-cong-ming">RAG 怎么让编程助手变聪明<a class="zola-anchor" href="#rag-zen-me-rang-bian-cheng-zhu-shou-bian-cong-ming" aria-label="Anchor link for: rag-zen-me-rang-bian-cheng-zhu-shou-bian-cong-ming" style="visibility: hidden;"></a>
</h2>
<p>结合 RAG，编程助手就能处理我们平时遇到的各种问题了。</p>
<p><img src="https://psiace.me/zh/posts/rag-in-coding-agent/coderag-bench.png" alt="CodeRAG Benchmark" /></p>
<p>整个过程大概是这样的：</p>
<h3 id="1-gao-qing-chu-ni-yao-gan-shen-me">1. <strong>搞清楚你要干什么</strong><a class="zola-anchor" href="#1-gao-qing-chu-ni-yao-gan-shen-me" aria-label="Anchor link for: 1-gao-qing-chu-ni-yao-gan-shen-me" style="visibility: hidden;"></a>
</h3>
<p>你说"给 API 加个用户认证"，助手得先理解：</p>
<ul>
<li>要 JWT、OAuth 还是别的方案？</li>
<li>现有代码哪里需要改？</li>
<li>你用的什么框架？</li>
</ul>
<p>然后开始工作——去翻文档找例子，把你的需求搞清楚。</p>
<h3 id="2-shou-ji-xiang-guan-zi-liao">2. <strong>收集相关资料</strong><a class="zola-anchor" href="#2-shou-ji-xiang-guan-zi-liao" aria-label="Anchor link for: 2-shou-ji-xiang-guan-zi-liao" style="visibility: hidden;"></a>
</h3>
<p>然后就是搜集阶段，像个勤快的实习生一样，到处找：</p>
<ul>
<li><strong>官方文档</strong>：框架的使用指南</li>
<li><strong>代码例子</strong>：你项目里或者开源项目的类似实现</li>
<li><strong>社区问答</strong>：StackOverflow、GitHub 上的讨论</li>
<li><strong>最佳实践</strong>：编码规范和安全建议</li>
</ul>
<p>把这些都混在一起，就是传说中的"知识汤"。</p>
<h3 id="3-xie-dai-ma-bing-ce-shi">3. <strong>写代码并测试</strong><a class="zola-anchor" href="#3-xie-dai-ma-bing-ce-shi" aria-label="Anchor link for: 3-xie-dai-ma-bing-ce-shi" style="visibility: hidden;"></a>
</h3>
<p>有了这些资料，助手就能写出比较靠谱的代码了。但它不会直接给你，而是先在沙箱里跑一遍：</p>
<ul>
<li>看看有没有明显的错误</li>
<li>确认确实能解决你的问题</li>
<li>有问题的话马上调整</li>
</ul>
<h3 id="4-chu-li-cheng-gong-he-shi-bai">4. <strong>处理成功和失败</strong><a class="zola-anchor" href="#4-chu-li-cheng-gong-he-shi-bai" aria-label="Anchor link for: 4-chu-li-cheng-gong-he-shi-bai" style="visibility: hidden;"></a>
</h3>
<p>代码跑通了当然好，但如果出错了，它不会放弃：</p>
<ul>
<li>分析错误信息</li>
<li>去找类似问题的解决方案</li>
<li>用新信息再试一遍</li>
</ul>
<p>这个循环让 Coding Agent 变得靠谱多了。</p>
<h3 id="5-jiao-fu-cheng-guo">5. <strong>交付成果</strong><a class="zola-anchor" href="#5-jiao-fu-cheng-guo" aria-label="Anchor link for: 5-jiao-fu-cheng-guo" style="visibility: hidden;"></a>
</h3>
<p>最后，助手会把完整的解决方案给你——不只是代码，还有说明文档。</p>
<hr />
<h2 id="zui-da-de-keng-shen-me-shi-hou-qu-cha-zi-liao">最大的坑：什么时候去查资料？<a class="zola-anchor" href="#zui-da-de-keng-shen-me-shi-hou-qu-cha-zi-liao" aria-label="Anchor link for: zui-da-de-keng-shen-me-shi-hou-qu-cha-zi-liao" style="visibility: hidden;"></a>
</h2>
<p>用 RAG 有个很关键的问题：<strong>什么时候该去查资料</strong>？</p>
<p>太早查可能漏掉重要信息，太晚查又会拖慢速度。我觉得这样比较合理：</p>
<ul>
<li>通用的东西（框架文档、编码规范）提前准备好</li>
<li>具体问题（调试、特殊需求）现查现用</li>
</ul>
<p>这样既不会太慢，也不会出错。</p>
<hr />
<h2 id="shen-me-xin-xi-gai-cun-shen-me-gai-diu">什么信息该存，什么该丢<a class="zola-anchor" href="#shen-me-xin-xi-gai-cun-shen-me-gai-diu" aria-label="Anchor link for: shen-me-xin-xi-gai-cun-shen-me-gai-diu" style="visibility: hidden;"></a>
</h2>
<p>不是所有信息都一样重要。有些东西（比如框架规则）得一直记着，有些（比如这次运行的日志）用完就可以扔了。</p>
<p><img src="https://psiace.me/zh/posts/rag-in-coding-agent/knowledge-soup.png" alt="Knowledge Soup" /></p>
<p>这样处理可能会是一个不错的路线：</p>
<table><thead><tr><th><strong>知识类型</strong></th><th><strong>怎么存</strong></th><th><strong>怎么找</strong></th></tr></thead><tbody>
<tr><td>编码规范</td><td>一直存着</td><td>知识图谱快速查找</td></tr>
<tr><td>文档教程</td><td>按版本存</td><td>语义搜索相关部分 + 代码结构映射</td></tr>
<tr><td>问答和代码库</td><td>先临时后永久</td><td>API 查询 + 缓存</td></tr>
<tr><td>运行时反馈</td><td>临时存储</td><td>即时检索和更新</td></tr>
</tbody></table>
<p>这样既不会太慢，也不会占太多空间。</p>
<blockquote>
<p>执行的上下文越长，无效的信息越多，也需要及时压缩和截断，保留真正有效的部分。</p>
</blockquote>
<hr />
<h2 id="xiang-shi-shi-de-hua-cong-jian-dan-kai-shi">想试试的话，从简单开始<a class="zola-anchor" href="#xiang-shi-shi-de-hua-cong-jian-dan-kai-shi" aria-label="Anchor link for: xiang-shi-shi-de-hua-cong-jian-dan-kai-shi" style="visibility: hidden;"></a>
</h2>
<p>如果你也想写个编程助手，但不想搞得太复杂，可以这样开始：</p>
<p><img src="https://psiace.me/zh/posts/rag-in-coding-agent/swe-agent.png" alt="SWE Agent" /></p>
<ol>
<li>先写一些规则和提示词</li>
<li>用简单的搜索工具找文档</li>
<li>写个脚本查 StackOverflow</li>
<li>用 <code>grep</code>、<code>lint</code> 这些工具收集反馈</li>
</ol>
<p>这样就有个基础版本了，后面再慢慢改进。</p>
<hr />
<h2 id="xie-zai-zui-hou">写在最后<a class="zola-anchor" href="#xie-zai-zui-hou" aria-label="Anchor link for: xie-zai-zui-hou" style="visibility: hidden;"></a>
</h2>
<p>Coding Agent 确实在改变编程的方式。它把"查资料"和"写代码"结合起来，让编程助手真正能帮上忙——理解你的需求、找到相关文件、写出能用的代码、帮你调试问题。</p>
<p>不管你是新手还是老手，这些效率工具总归能让工作轻松一些。如果你想自己搞一个，建议从简单的开始，慢慢试验。反正现在这个领域变化很快，说不定你就能做出下一个爆款工具。</p>
<p>总之，这个方向还是很有意思的，值得关注。</p>
RAG 没有捷径
2025-04-17T00:00:00+00:00
2025-04-17T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/rag-is-the-way/
<p>去年我从数据库基础设施跳进 RAG 项目时，以为终于能摆脱底层细节，结果是另一种更复杂的基础设施扑面而来。RAG 看似应用层，其实处处是工程化的坑。</p>
<h2 id="jian-suo-bu-zhi-shi-zhao-dao">检索：不只是“找到”<a class="zola-anchor" href="#jian-suo-bu-zhi-shi-zhao-dao" aria-label="Anchor link for: jian-suo-bu-zhi-shi-zhao-dao" style="visibility: hidden;"></a>
</h2>
<p>传统搜索里，我们调索引、调排序，指标相对稳定。RAG 的检索要面对的是语义空间——向量近邻、模型偏差、上下文漂移。今天 QA 能命中“三季度发货策略”，明天可能因为语境不同完全跑偏。检索的目标从“找到哪条记录”变成“理解用户真正想说什么，并确保返回的语段能支撑后续推理”。</p>
<h2 id="agent-bie-bei-ming-zi-pian-liao">Agent：别被名字骗了<a class="zola-anchor" href="#agent-bie-bei-ming-zi-pian-liao" aria-label="Anchor link for: agent-bie-bei-ming-zi-pian-liao" style="visibility: hidden;"></a>
</h2>
<p>大家给 Agent 起了很多酷炫的名字：规划代理、推理代理、工具代理……但它们大多还是条件语句堆出来的工作流。区别只是条件不是硬编码，而是 LLM 动态生成。重点不在“更智能”，而在“如何把工具、状态、反馈闭环结构化”。我们需要的是一个可观察、可替换的流程引擎，模型只是其中的决策组件。</p>
<h2 id="grounding-truth-zui-hou-de-mao-dian">Grounding Truth：最后的锚点<a class="zola-anchor" href="#grounding-truth-zui-hou-de-mao-dian" aria-label="Anchor link for: grounding-truth-zui-hou-de-mao-dian" style="visibility: hidden;"></a>
</h2>
<p>没有扎实的事实校验，RAG 系统只是会讲好听故事的随机鹦鹉。Grounding 不是选配，而是价值锚定。你得持续补充可验证的知识底座，让领域专家参与反馈循环，设计清晰的“证据链”输出格式。否则，Agent 再聪明也只是在幻觉上做推理。</p>
<h2 id="fu-za-xing-cong-na-li-lai">复杂性从哪里来<a class="zola-anchor" href="#fu-za-xing-cong-na-li-lai" aria-label="Anchor link for: fu-za-xing-cong-na-li-lai" style="visibility: hidden;"></a>
</h2>
<ul>
<li><strong>数据形态多样</strong>：PDF、截图、音视频、传感器数据同时存在，且要保持语义一致。</li>
<li><strong>一致性概念模糊</strong>：知识会被实时更新，旧答案随时过期。你需要定义“足够新”“足够可信”的标准。</li>
<li><strong>成本与体验拉扯</strong>：检索准确度、上下文长度、延迟、推理深度，一环牵动一环。</li>
</ul>
<p>这比建一个数据库、一个 API 难多了，但也更有意思。</p>
<h2 id="wei-shen-me-huan-yao-gan">为什么还要干<a class="zola-anchor" href="#wei-shen-me-huan-yao-gan" aria-label="Anchor link for: wei-shen-me-huan-yao-gan" style="visibility: hidden;"></a>
</h2>
<p>因为我们在重新定义“信息系统”：</p>
<ul>
<li>让系统理解人的意图，而不是死背关键词；</li>
<li>让工具链能自我学习、自动拼装；</li>
<li>把抽象的语言推理和现实世界的事实连接起来。</li>
</ul>
<p>这是一种新的基础设施：检索、智能体与真实感三元同构。谁能把这三者编排好，谁就掌握下一代知识系统的主动权。</p>
<p>所以，当别人问我为什么离开数据库领域去做 AI 应用时，我会说：“我没离开基础设施，我只是换了一种方式去构建它。”</p>
<p>现在，请允许我回去调向量量化、训几个不听话的 Agent，并确保文本切分策略不会把事实撕裂。这，就是日常的 RAG 工程。</p>
NebulaGraph MCP Server 正式开源！探索 AI+图数据库无限可能
2025-03-11T00:00:00+00:00
2025-03-11T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/announcing-nebulagraph-mcp-server-v010/
<h2 id="yi-bei-jing">一、背景<a class="zola-anchor" href="#yi-bei-jing" aria-label="Anchor link for: yi-bei-jing" style="visibility: hidden;"></a>
</h2>
<p>过去几周，Model Context Protocol (MCP) 在技术社区中引发了广泛的讨论和关注。借此机会，我参与了几个相关的开源项目，包括为 <strong>LlamaIndex 官方仓库贡献了 McpToolSpec 实现</strong>，以及和 Xuanwo、FrostMing 合作开发了一版 <strong>Model Context Protocol Server for Apache OpenDAL™</strong>。</p>
<p>MCP 是目前唯一一个在生态上具有优势的标准。在这一背景下，我们 <strong>基于 NebulaGraph 3.x 实现了一个简单的 NebulaGraph MCP Server，作为 NebulaGraph X MCP 生态中的第一个基础组件，供大家探索 AI 与图数据库结合的可能性</strong>，希望能够看到更多在这个模式下的有趣工作。</p>
<h2 id="er-model-context-protocol-mcp">二、Model Context Protocol (MCP)<a class="zola-anchor" href="#er-model-context-protocol-mcp" aria-label="Anchor link for: er-model-context-protocol-mcp" style="visibility: hidden;"></a>
</h2>
<p>MCP 是由 Anthropic 团队推出的一项开放协议，旨在为 AI 系统提供统一的、高效的方式访问多种数据资源。通过采用客户端-服务器架构，MCP 将数据访问标准化，解决了传统 AI 系统在不同数据源之间的碎片化问题。</p>
<h3 id="mcp-he-xin-te-dian">MCP 核心特点<a class="zola-anchor" href="#mcp-he-xin-te-dian" aria-label="Anchor link for: mcp-he-xin-te-dian" style="visibility: hidden;"></a>
</h3>
<ol>
<li><strong>标准化的通信方式</strong>：通过 MCP，AI 助手能够有效地访问各种数据源，比如本地数据、远程服务和企业工具。</li>
<li><strong>开放性与生态优势</strong>：目前 MCP 社区中已有近 1000 个 MCP Server 实现，覆盖搜索、天气、数据库等多个领域，支持工具的快速接入。</li>
<li><strong>灵活的架构</strong>：通过定义客户端和服务端的交互协议，MCP 为开发者提供了构建可扩展、可复用系统的基础。</li>
</ol>
<p>虽然目前在安全性和可靠性上仍有一些挑战，但随着协议规范的完善和成熟开发模式的引入，这些问题将逐步得到解决。</p>
<h2 id="san-nebulagraph-mcp-server-gong-neng">三、NebulaGraph MCP Server 功能<a class="zola-anchor" href="#san-nebulagraph-mcp-server-gong-neng" aria-label="Anchor link for: san-nebulagraph-mcp-server-gong-neng" style="visibility: hidden;"></a>
</h2>
<p>由于最近一段时间一直围绕 GraphRAG 和 Agentic Workflow 做一些工作，利用大模型和智能体进行图上数据的洞见和挖掘是一个非常重要的议题。为此，我快速开发了 NebulaGraph MCP Server，以支持 NebulaGraph 3.x 作为工具接入 MCP 生态，供语言模型（如 Claude、GPT 等）调用和使用。</p>
<p>目前 <strong>NebulaGraph MCP Server 基于 FastMCP 实现，遵循 MCP 的核心规范，旨在提供高效、轻量的图数据库连接服务。</strong> 通过将 NebulaGraph 的功能暴露为标准化的工具接口，该 Server 能够让大模型轻松调用 NebulaGraph 数据，实现简单的图探索任务。</p>
<ul>
<li><strong>多种传输方式</strong>：
<ul>
<li>支持 stdio 和 SSE 两种传输模式，满足不同开发和部署场景的需求。</li>
</ul>
</li>
<li><strong>基础图探索能力</strong>：
<ul>
<li>图空间（Graph Space）列出：允许模型查询可用的图空间。</li>
<li>模式（Schema）查询：支持查询指定图空间的模式定义。</li>
<li>查询执行（Query Execution）：支持通过 MCP Server 执行 NebulaGraph 查询。</li>
</ul>
</li>
<li><strong>内置算子模板</strong>：
<ul>
<li>实现了路径搜索和邻居发现等常用操作的模板，方便语言模型按需调用这些工具，快速获取图数据的初步洞察（Insight）。</li>
</ul>
</li>
</ul>
<p>为了展示它的效果，我基于 LlamaIndex 中的 McpToolSpec 和 ReActAgent 构建了一个简单的示例，下面是对应的截图：</p>
<p><img src="https://psiace.me/zh/posts/announcing-nebulagraph-mcp-server-v010/llamaindex-with-nebulagraph-mcp.png" alt="LlamaIndex with NebulaGraph MCP" /></p>
<h2 id="si-jie-yu">四、结语<a class="zola-anchor" href="#si-jie-yu" aria-label="Anchor link for: si-jie-yu" style="visibility: hidden;"></a>
</h2>
<p><strong>NebulaGraph MCP Server</strong> 是对 MCP 生态的一个初步尝试，旨在为语言模型和图数据库的结合提供一个起点。随着协议的逐步成熟和生态的扩展，我们期待它能够在更多真实场景中发挥价值。如果您对这一方向感兴趣，欢迎一起探索、尝试！</p>
把 MCP 工具塞进 LlamaIndex 工作流
2025-02-11T00:00:00+00:00
2025-02-11T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/integrate-mcp-tools-into-llamaindex/
<h2 id="yi-qian-yan">一、前言<a class="zola-anchor" href="#yi-qian-yan" aria-label="Anchor link for: yi-qian-yan" style="visibility: hidden;"></a>
</h2>
<p>本文主要介绍了如何将 MCP（Model Context Protocol，模型上下文协议）工具转换为可以直接使用的 LlamaIndex 工具，使 LlamaIndex 用户能像使用 Claude, Cursor 等现代 AI 应用一样无缝集成这些服务。</p>
<h2 id="er-ji-shu-bei-jing">二、技术背景<a class="zola-anchor" href="#er-ji-shu-bei-jing" aria-label="Anchor link for: er-ji-shu-bei-jing" style="visibility: hidden;"></a>
</h2>
<h3 id="2-1-shen-me-shi-mcp-xie-yi">2.1 什么是 MCP 协议？<a class="zola-anchor" href="#2-1-shen-me-shi-mcp-xie-yi" aria-label="Anchor link for: 2-1-shen-me-shi-mcp-xie-yi" style="visibility: hidden;"></a>
</h3>
<p>MCP（模型上下文协议，https://modelcontextprotocol.io）是面向 AI 应用交互的服务构建协议。开发者可通过该协议构建具备数据资源（resources）、功能工具（tools）和提示模板（prompts）的服务端点。例如，我们可以定义获取 IP 详细信息的 fetch_ipinfo 工具：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-entity z-name">@</span><span class="z-entity z-name">mcp</span><span class="z-entity z-name">.</span><span class="z-entity z-name">tool</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span class="z-storage z-type">async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> fetch_ipinfo</span><span>(</span><span class="z-variable z-parameter z-function">ip</span><span>:</span><span class="z-support"> str</span><span class="z-keyword"> |</span><span class="z-constant"> None</span><span class="z-keyword"> =</span><span class="z-constant"> None</span><span>,</span><span class="z-keyword"> **</span><span class="z-variable z-parameter z-function">kwargs</span><span>)</span><span> -></span><span> IPDetails</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span><span class="z-string">获取指定IP的详细信息</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> 参数:</span></span>
<span class="giallo-l"><span class="z-string"> ip(str or None): 目标 IP 地址，格式如 192.168.1.1</span></span>
<span class="giallo-l"><span class="z-string"> **kwargs: 传递给 IPInfo 处理器的附加参数</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> 返回:</span></span>
<span class="giallo-l"><span class="z-string"> IPDetails: 包含城市、时区等信息的结构化数据</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span></span>
<span class="giallo-l"><span> handler</span><span class="z-keyword"> =</span><span> ipinfo</span><span>.</span><span>getHandler</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> access_token</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>environ</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">IPINFO_API_TOKEN</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> headers</span><span class="z-keyword">=</span><span>{</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">user-agent</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">basic-mcp-server</span><span class="z-punctuation z-definition z-string">"</span><span>}</span><span>,</span></span>
<span class="giallo-l"><span class="z-keyword"> **</span><span>kwargs</span><span>,</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"><span> details</span><span class="z-keyword"> =</span><span> handler</span><span>.</span><span>getDetails</span><span>(</span><span class="z-variable">ip_address</span><span class="z-keyword">=</span><span>ip</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> IPDetails</span><span>(</span><span class="z-keyword">**</span><span>details</span><span>.</span><span>all</span><span>)</span></span></code></pre><h3 id="2-2-llamaindex-kuang-jia-te-zheng">2.2 LlamaIndex 框架特征<a class="zola-anchor" href="#2-2-llamaindex-kuang-jia-te-zheng" aria-label="Anchor link for: 2-2-llamaindex-kuang-jia-te-zheng" style="visibility: hidden;"></a>
</h3>
<p>LlamaIndex（https://github.com/run-llama/llama_index）是构建知识索引系统的核心框架，其核心价值在于将外部信息结构化地接入大语言模型，实现高效的信息检索、智能问答和对话生成。当需要集成动态数据源时，将 MCP 工具转换为 LlamaIndex 工具成为关键技术需求。</p>
<p>在 LlamaIndex 中，NebulaGraph 已经有两种方法实现 GraphRAG：KnowledgeGraphIndex 用来对任何私有数据从零构建知识图谱（基于 LLM 或者其他语言模型），再 4 行代码进行 Graph RAG：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>graph_store</span><span class="z-keyword"> =</span><span> NebulaGraphStore</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> space_name</span><span class="z-keyword">=</span><span>space_name</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> edge_types</span><span class="z-keyword">=</span><span>edge_types</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> rel_prop_names</span><span class="z-keyword">=</span><span>rel_prop_names</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> tags</span><span class="z-keyword">=</span><span>tags</span><span>,</span></span>
<span class="giallo-l"><span>)</span></span>
<span class="giallo-l"><span>storage_context</span><span class="z-keyword"> =</span><span> StorageContext</span><span>.</span><span>from_defaults</span><span>(</span><span class="z-variable">graph_store</span><span class="z-keyword">=</span><span>graph_store</span><span>)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Build KG</span></span>
<span class="giallo-l"><span>kg_index</span><span class="z-keyword"> =</span><span> KnowledgeGraphIndex</span><span>.</span><span>from_documents</span><span>(</span></span>
<span class="giallo-l"><span> documents</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> storage_context</span><span class="z-keyword">=</span><span>storage_context</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> max_triplets_per_chunk</span><span class="z-keyword">=</span><span class="z-constant">10</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> space_name</span><span class="z-keyword">=</span><span>space_name</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> edge_types</span><span class="z-keyword">=</span><span>edge_types</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> rel_prop_names</span><span class="z-keyword">=</span><span>rel_prop_names</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> tags</span><span class="z-keyword">=</span><span>tags</span><span>,</span></span>
<span class="giallo-l"><span>)</span></span>
<span class="giallo-l"><span>kg_query_engine</span><span class="z-keyword"> =</span><span> kg_index</span><span>.</span><span>as_query_engine</span><span>(</span><span>)</span></span></code></pre>
<p>KnowledgeGraphRAGQueryEngine 则可以在任何已经存在的知识图谱上进行 GraphRAG:</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>graph_store</span><span class="z-keyword"> =</span><span> NebulaGraphStore</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> space_name</span><span class="z-keyword">=</span><span>space_name</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> edge_types</span><span class="z-keyword">=</span><span>edge_types</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> rel_prop_names</span><span class="z-keyword">=</span><span>rel_prop_names</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> tags</span><span class="z-keyword">=</span><span>tags</span><span>,</span></span>
<span class="giallo-l"><span>)</span></span>
<span class="giallo-l"><span>storage_context</span><span class="z-keyword"> =</span><span> StorageContext</span><span>.</span><span>from_defaults</span><span>(</span><span class="z-variable">graph_store</span><span class="z-keyword">=</span><span>graph_store</span><span>)</span></span>
<span class="giallo-l"><span>graph_rag_query_engine</span><span class="z-keyword"> =</span><span> KnowledgeGraphRAGQueryEngine</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> storage_context</span><span class="z-keyword">=</span><span>storage_context</span><span>,</span></span>
<span class="giallo-l"><span>)</span></span></code></pre><h2 id="san-wei-shen-me-xu-yao-jiang-mcp-ji-cheng-zhi-llamaindex">三、为什么需要将 MCP 集成至 LlamaIndex<a class="zola-anchor" href="#san-wei-shen-me-xu-yao-jiang-mcp-ji-cheng-zhi-llamaindex" aria-label="Anchor link for: san-wei-shen-me-xu-yao-jiang-mcp-ji-cheng-zhi-llamaindex" style="visibility: hidden;"></a>
</h2>
<p>在实际 AI 应用开发中，集成 MCP 工具主要解决以下需求：</p>
<ul>
<li>功能复用：利用现有 MCP 生态（项目列表见 https://github.com/AlexMili/Awesome-MCP）快速扩展系统能力</li>
<li>流程统一：建立标准化工具调用范式，简化大模型对外部 API 的调用复杂度</li>
<li>自动化管理：通过自动转换机制实现 MCP 工具到 LlamaIndex FunctionTool 对象的映射，便于 Agent 自动调度</li>
</ul>
<p>该集成方案可以有效降低开发成本，同时发挥 LlamaIndex 在上下文管理和对话生成方面的优势。</p>
<h2 id="si-ji-shu-shi-xian-fang-an">四、技术实现方案<a class="zola-anchor" href="#si-ji-shu-shi-xian-fang-an" aria-label="Anchor link for: si-ji-shu-shi-xian-fang-an" style="visibility: hidden;"></a>
</h2>
<p>实现流程包含三个关键阶段：</p>
<ul>
<li>MCP 服务通信：通过 MCPClient 类建立服务连接，支持工具发现（list_tools）和调用执行（call_tool）</li>
<li>适配器构建：定义 MCPToolAdapter 类，将 MCP 工具元数据转换为 LlamaIndex 的 FunctionTool 对象</li>
<li>智能代理集成：在 LlamaIndex Agent 中加载转换后的工具，实现自动化调用</li>
</ul>
<h2 id="wu-he-xin-dai-ma-jie-xi">五、核心代码解析<a class="zola-anchor" href="#wu-he-xin-dai-ma-jie-xi" aria-label="Anchor link for: wu-he-xin-dai-ma-jie-xi" style="visibility: hidden;"></a>
</h2>
<h3 id="xie-yi-zhuan-huan-gua-pei-qi">协议转换适配器<a class="zola-anchor" href="#xie-yi-zhuan-huan-gua-pei-qi" aria-label="Anchor link for: xie-yi-zhuan-huan-gua-pei-qi" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>core</span><span>.</span><span>tools</span><span class="z-keyword"> import</span><span> FunctionTool</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> pydantic</span><span class="z-keyword"> import</span><span> create_model</span><span>,</span><span> BaseModel</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> MCPToolAdapter</span><span>:</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-support"> __init__</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> client</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>client</span><span class="z-keyword"> =</span><span> client</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> list_tools</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> tools</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-language"> self</span><span>.</span><span>client</span><span>.</span><span>list_tools</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> [</span></span>
<span class="giallo-l"><span> FunctionTool</span><span>.</span><span>from_defaults</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> fn</span><span class="z-keyword">=</span><span class="z-variable z-language">self</span><span>.</span><span>_create_tool_fn</span><span>(</span><span>tool</span><span>.</span><span>name</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> name</span><span class="z-keyword">=</span><span>tool</span><span>.</span><span>name</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> description</span><span class="z-keyword">=</span><span>tool</span><span>.</span><span>description</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> fn_schema</span><span class="z-keyword">=</span><span class="z-variable z-language">self</span><span>.</span><span>_create_pydantic_model</span><span>(</span><span>tool</span><span>.</span><span>schema</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span> )</span><span class="z-keyword"> for</span><span> tool</span><span class="z-keyword"> in</span><span> tools</span></span>
<span class="giallo-l"><span> ]</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> _create_pydantic_model</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> json_schema</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 实现JSON Schema到Pydantic模型的动态转换</span></span>
<span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h3 id="lei-xing-xi-tong-ying-she">类型系统映射<a class="zola-anchor" href="#lei-xing-xi-tong-ying-she" aria-label="Anchor link for: lei-xing-xi-tong-ying-she" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">JSON_TYPE_MAPPING</span><span class="z-keyword"> =</span><span> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-support"> str</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">number</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-support"> float</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-support"> int</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">boolean</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-support"> bool</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-support"> dict</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">"</span><span>:</span><span class="z-support"> list</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> create_dynamic_model</span><span>(</span><span class="z-variable z-parameter z-function">schema</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> fields</span><span class="z-keyword"> =</span><span> {</span><span>}</span></span>
<span class="giallo-l"><span class="z-keyword"> for</span><span> name</span><span>,</span><span> prop</span><span class="z-keyword"> in</span><span> schema</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">properties</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>.</span><span>items</span><span>(</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> py_type</span><span class="z-keyword"> =</span><span class="z-constant"> JSON_TYPE_MAPPING</span><span>[</span><span>prop</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>]</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> name</span><span class="z-keyword"> in</span><span> schema</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">required</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span> [</span><span>]</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> fields</span><span>[</span><span>name</span><span>]</span><span class="z-keyword"> =</span><span> (</span><span>py_type</span><span>,</span><span> Field</span><span>(</span><span class="z-constant">...</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span>
<span class="giallo-l"><span> fields</span><span>[</span><span>name</span><span>]</span><span class="z-keyword"> =</span><span> (</span><span>Optional</span><span>[</span><span>py_type</span><span>]</span><span>,</span><span> Field</span><span>(</span><span class="z-constant">None</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> create_model</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">DynamicModel</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-keyword"> **</span><span>fields</span><span>)</span></span></code></pre><h3 id="fu-wu-diao-yong-feng-zhuang">服务调用封装<a class="zola-anchor" href="#fu-wu-diao-yong-feng-zhuang" aria-label="Anchor link for: fu-wu-diao-yong-feng-zhuang" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> fetch_ipinfo_wrapper</span><span>(</span><span class="z-keyword">**</span><span class="z-variable z-parameter z-function">kwargs</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-keyword"> await</span><span> mcp_client</span><span>.</span><span>call_tool</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">fetch_ipinfo</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span> kwargs</span><span>)</span></span></code></pre><h3 id="guan-jian-ji-shu-chuang-xin-dian">关键技术创新点<a class="zola-anchor" href="#guan-jian-ji-shu-chuang-xin-dian" aria-label="Anchor link for: guan-jian-ji-shu-chuang-xin-dian" style="visibility: hidden;"></a>
</h3>
<ul>
<li>动态模式转换：实现 JSON Schema 到 Pydantic 模型的运行时转换，保证参数校验的严格性</li>
<li>异步调用管道：基于 Python asyncio 构建非阻塞式服务调用，提升工具执行效率</li>
<li>协议抽象层：通过适配器模式解耦 MCP 协议与 LlamaIndex 框架，保证系统扩展性</li>
</ul>
<p>将 MCP 工具的输入参数转换为 Pydantic 模型的原因在于：MCP 工具使用 JSON Schema 格式定义输入参数（在工具对象的 inputSchema 中，类型为 Dict[str, Any] ），而 create_model_from_json_schema 函数将其转换为 Pydantic 模型，该模型用作 LlamaIndex 中 FunctionTool 的 fn_schema。</p>
<h2 id="liu-llamaindex-zhong-de-mcp-gong-ju-diao-yong-shi-jian">六、LlamaIndex 中的 MCP 工具调用实践<a class="zola-anchor" href="#liu-llamaindex-zhong-de-mcp-gong-ju-diao-yong-shi-jian" aria-label="Anchor link for: liu-llamaindex-zhong-de-mcp-gong-ju-diao-yong-shi-jian" style="visibility: hidden;"></a>
</h2>
<p>以下代码来自 llamaindex_mcp_example.py，完整展示了 MCPToolAdapter 与 LlamaIndex 的集成方式：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> os</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>core</span><span>.</span><span>llms</span><span class="z-keyword"> import</span><span> ChatMessage</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>core</span><span>.</span><span>agent</span><span class="z-keyword"> import</span><span> ReActAgent</span><span>,</span><span> ReActChatFormatter</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>core</span><span>.</span><span>agent</span><span>.</span><span>react</span><span>.</span><span>prompts</span><span class="z-keyword"> import</span><span class="z-constant"> REACT_CHAT_SYSTEM_HEADER</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>llms</span><span>.</span><span>azure_openai</span><span class="z-keyword"> import</span><span> AzureOpenAI</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llamaindex_mcp_adapter</span><span class="z-keyword"> import</span><span> MCPToolAdapter</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> mcp_client</span><span class="z-keyword"> import</span><span> MCPClient</span></span>
<span class="giallo-l"><span class="z-keyword">import</span><span> anyio</span></span>
<span class="giallo-l"><span class="z-keyword">import</span><span> dotenv</span></span>
<span class="giallo-l"><span class="z-keyword">import</span><span> argparse</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>dotenv</span><span>.</span><span>load_dotenv</span><span>(</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> 系统级指令模板</span></span>
<span class="giallo-l"><span class="z-constant">SYSTEM_PROMPT</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> """</span><span class="z-constant">\</span></span>
<span class="giallo-l"><span class="z-string">您是一个智能法律助手</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string">在回答用户问题前，必须通过IP信息确认用户所在司法管辖区</span></span>
<span class="giallo-l"><span class="z-string">操作规则：</span></span>
<span class="giallo-l"><span class="z-string">- 当涉及地理位置、时区等问题时，自动调用fetch_ipinfo工具</span></span>
<span class="giallo-l"><span class="z-string">- 法律咨询类问题需结合IP所在国家/地区法律体系</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string">"""</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_agent</span><span>(</span><span class="z-variable z-parameter z-function">adapter</span><span>:</span><span> MCPToolAdapter</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span><span class="z-string">智能代理初始化函数</span><span class="z-punctuation z-definition z-string">"""</span></span>
<span class="giallo-l"><span> tools</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span> adapter</span><span>.</span><span>list_tools</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 获取MCP工具列表</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 配置Azure OpenAI大语言模型</span></span>
<span class="giallo-l"><span> llm</span><span class="z-keyword"> =</span><span> AzureOpenAI</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> model</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>environ</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">AZURE_OPENAI_MODEL</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">gpt-4</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> max_tokens</span><span class="z-keyword">=</span><span class="z-support">int</span><span>(</span><span>os</span><span>.</span><span>environ</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">AZURE_OPENAI_MAX_TOKENS</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-constant"> 4096</span><span>)</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> azure_endpoint</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>environ</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">AZURE_OPENAI_ENDPOINT</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> api_key</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>environ</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">AZURE_OPENAI_API_KEY</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> api_version</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>environ</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">AZURE_OPENAI_API_VERSION</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> engine</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>environ</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">AZURE_OPENAI_ENGINE</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 构建ReAct智能代理</span></span>
<span class="giallo-l"><span> agent</span><span class="z-keyword"> =</span><span> ReActAgent</span><span>.</span><span>from_tools</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> llm</span><span class="z-keyword">=</span><span>llm</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> tools</span><span class="z-keyword">=</span><span class="z-support">list</span><span>(</span><span>tools</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> react_chat_formatter</span><span class="z-keyword">=</span><span>ReActChatFormatter</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> system_header</span><span class="z-keyword">=</span><span class="z-constant">SYSTEM_PROMPT</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-constant">\n</span><span class="z-punctuation z-definition z-string">"</span><span class="z-keyword"> +</span><span class="z-constant"> REACT_CHAT_SYSTEM_HEADER</span><span>,</span></span>
<span class="giallo-l"><span> )</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> max_iterations</span><span class="z-keyword">=</span><span class="z-constant">20</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 限制最大推理步数</span></span>
<span class="giallo-l"><span class="z-variable"> verbose</span><span class="z-keyword">=</span><span class="z-constant">True</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 启用详细日志</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> agent</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> handle_user_message</span><span>(</span><span class="z-variable z-parameter z-function">message_content</span><span>:</span><span class="z-support"> str</span><span>,</span><span class="z-variable z-parameter z-function"> agent</span><span>:</span><span> ReActAgent</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span><span class="z-string">消息处理流水线</span><span class="z-punctuation z-definition z-string">"""</span></span>
<span class="giallo-l"><span> user_message</span><span class="z-keyword"> =</span><span> ChatMessage</span><span>.</span><span>from_str</span><span>(</span><span class="z-variable">role</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">user</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> content</span><span class="z-keyword">=</span><span>message_content</span><span>)</span></span>
<span class="giallo-l"><span> response</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span> agent</span><span>.</span><span>achat</span><span>(</span><span class="z-variable">message</span><span class="z-keyword">=</span><span>user_message</span><span>.</span><span>content</span><span>)</span></span>
<span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">"</span><span class="z-string">[智能代理响应] </span><span class="z-constant">{</span><span>response</span><span>.</span><span>response</span><span class="z-constant">}</span><span class="z-string">"</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">if</span><span class="z-support z-variable"> __name__</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">__main__</span><span class="z-punctuation z-definition z-string">"</span><span>:</span></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> main</span><span>(</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 命令行参数解析</span></span>
<span class="giallo-l"><span> parser</span><span class="z-keyword"> =</span><span> argparse</span><span>.</span><span>ArgumentParser</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span> parser</span><span>.</span><span>add_argument</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">--client_type</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> choices</span><span class="z-keyword">=</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">sse</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">stdio</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> default</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">stdio</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> help</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">连接模式：sse(Server-Sent Events)或stdio(标准输入输出)</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span> args</span><span class="z-keyword"> =</span><span> parser</span><span>.</span><span>parse_args</span><span>(</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> MCP客户端初始化</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> args</span><span>.</span><span>client_type</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">sse</span><span class="z-punctuation z-definition z-string">"</span><span>:</span></span>
<span class="giallo-l"><span> client</span><span class="z-keyword"> =</span><span> MCPClient</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">http://0.0.0.0:8000/sse</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> SSE长连接模式</span></span>
<span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span>
<span class="giallo-l"><span> client</span><span class="z-keyword"> =</span><span> MCPClient</span><span>(</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 子进程模式</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">./venv/bin/python</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">mcp_server.py</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">--server_type</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">stdio</span><span class="z-punctuation z-definition z-string">"</span><span>]</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 工具适配器初始化</span></span>
<span class="giallo-l"><span> adapter</span><span class="z-keyword"> =</span><span> MCPToolAdapter</span><span>(</span><span>client</span><span>)</span></span>
<span class="giallo-l"><span> agent</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span> get_agent</span><span>(</span><span>adapter</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 执行测试用例</span></span>
<span class="giallo-l"><span class="z-keyword"> await</span><span> handle_user_message</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">我的IP所在城市是哪里？</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span> agent</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> await</span><span> handle_user_message</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">持有大麻在我国是否合法？</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span> agent</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span> anyio</span><span>.</span><span>run</span><span>(</span><span>main</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 启动异步运行时</span></span></code></pre><h3 id="guan-jian-shi-xian-jie-xi">关键实现解析<a class="zola-anchor" href="#guan-jian-shi-xian-jie-xi" aria-label="Anchor link for: guan-jian-shi-xian-jie-xi" style="visibility: hidden;"></a>
</h3>
<ul>
<li>工具获取机制：
<ul>
<li>通过 adapter.list_tools() 动态加载 MCP 服务端注册的工具列表</li>
<li>自动将每个 MCP 工具转换为 LlamaIndex 的 FunctionTool 对象</li>
</ul>
</li>
<li>智能代理配置：
<ul>
<li>使用 Azure OpenAI 作为底层大语言模型引擎</li>
<li>集成 ReAct 推理框架，支持多步工具调用</li>
<li>设置 20 步的最大推理深度防止无限循环</li>
</ul>
</li>
<li>消息处理流程：
<ul>
<li>将用户输入封装为标准化 ChatMessage</li>
<li>通过 agent.achat() 触发自动化工具调用链</li>
</ul>
</li>
</ul>
<h2 id="qi-yun-xing-demo">七、运行 Demo<a class="zola-anchor" href="#qi-yun-xing-demo" aria-label="Anchor link for: qi-yun-xing-demo" style="visibility: hidden;"></a>
</h2>
<h3 id="7-1-biao-zhun-shu-ru-shu-chu-mo-shi">7.1 标准输入输出模式<a class="zola-anchor" href="#7-1-biao-zhun-shu-ru-shu-chu-mo-shi" aria-label="Anchor link for: 7-1-biao-zhun-shu-ru-shu-chu-mo-shi" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">python</span><span class="z-string"> llamaindex_mcp_example.py</span><span class="z-constant"> -</span><span class="z-constant">-client_type</span><span class="z-string"> stdio</span></span></code></pre><h3 id="zhi-xing-shu-chu-shi-li">执行输出示例<a class="zola-anchor" href="#zhi-xing-shu-chu-shi-li" aria-label="Anchor link for: zhi-xing-shu-chu-shi-li" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[DEBUG] 检测到ListToolsRequest协议请求</span></span>
<span class="giallo-l"><span>[工具调用] 步骤ID: ede14770-91c9-428b... | 输入: 我的IP所在城市是哪里？</span></span>
<span class="giallo-l"><span>[推理日志] 当前用户语言：中文，需调用工具获取数据</span></span>
<span class="giallo-l"><span>[动作触发] fetch_ipinfo | 参数: {}</span></span>
<span class="giallo-l"><span>[网络请求] 调用MCP工具耗时128ms</span></span>
<span class="giallo-l"><span>[观察结果] {"ip": "183.193.123.192", "city": "上海", "country": "CN"...}</span></span>
<span class="giallo-l"><span>[最终响应] 您的IP所在城市为上海</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>[法律咨询] 步骤ID: e728f5d0-6c0e-454a... | 输入: 持有大麻是否合法？</span></span>
<span class="giallo-l"><span>[推理日志] 已确认用户所在国家：中国</span></span>
<span class="giallo-l"><span>[知识库检索] 加载中国刑法第357条</span></span>
<span class="giallo-l"><span>[最终响应] 根据中国法律，持有大麻属违法行为，最高可判处有期徒刑</span></span></code></pre><h3 id="7-2-sse-fu-wu-mo-shi">7.2 SSE 服务模式<a class="zola-anchor" href="#7-2-sse-fu-wu-mo-shi" aria-label="Anchor link for: 7-2-sse-fu-wu-mo-shi" style="visibility: hidden;"></a>
</h3>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> 终端1：启动SSE服务端</span></span>
<span class="giallo-l"><span class="z-entity z-name">python</span><span class="z-string"> mcp_server.py</span><span class="z-constant"> -</span><span class="z-constant">-server_type</span><span class="z-string"> sse</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> 终端2：运行客户端</span></span>
<span class="giallo-l"><span class="z-entity z-name">python</span><span class="z-string"> llamaindex_mcp_example.py</span><span class="z-constant"> -</span><span class="z-constant">-client_type</span><span class="z-string"> sse</span></span></code></pre><h2 id="ba-ji-shu-fang-an-zong-jie">八、技术方案总结<a class="zola-anchor" href="#ba-ji-shu-fang-an-zong-jie" aria-label="Anchor link for: ba-ji-shu-fang-an-zong-jie" style="visibility: hidden;"></a>
</h2>
<p>通过以下三步实现深度集成：</p>
<h3 id="xie-yi-tong-xin-ceng">协议通信层<a class="zola-anchor" href="#xie-yi-tong-xin-ceng" aria-label="Anchor link for: xie-yi-tong-xin-ceng" style="visibility: hidden;"></a>
</h3>
<ul>
<li>基于 MCPClient 实现服务发现与工具调用</li>
<li>支持 SSE/STDIO 双模连接，适应不同部署场景</li>
</ul>
<h3 id="lei-xing-zhuan-huan-ceng">类型转换层<a class="zola-anchor" href="#lei-xing-zhuan-huan-ceng" aria-label="Anchor link for: lei-xing-zhuan-huan-ceng" style="visibility: hidden;"></a>
</h3>
<ul>
<li>动态将 JSON Schema 转换为 Pydantic 模型</li>
<li>实现参数自动校验与类型提示</li>
</ul>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> create_dynamic_model</span><span>(</span><span class="z-variable z-parameter z-function">schema</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 自动生成带字段描述的Pydantic模型</span></span>
<span class="giallo-l"><span> fields</span><span class="z-keyword"> =</span><span> {</span></span>
<span class="giallo-l"><span> name</span><span>:</span><span> (</span><span>map_type</span><span>(</span><span>prop</span><span>)</span><span>,</span><span> Field</span><span>(</span><span class="z-constant">...</span><span>,</span><span class="z-variable"> description</span><span class="z-keyword">=</span><span>prop</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">description</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> for</span><span> name</span><span>,</span><span> prop</span><span class="z-keyword"> in</span><span> schema</span><span>[</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">properties</span><span class="z-punctuation z-definition z-string">"</span><span>]</span><span>.</span><span>items</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> create_model</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">DynamicModel</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-keyword"> **</span><span>fields</span><span>)</span></span></code></pre><h3 id="zhi-neng-dai-li-ceng">智能代理层<a class="zola-anchor" href="#zhi-neng-dai-li-ceng" aria-label="Anchor link for: zhi-neng-dai-li-ceng" style="visibility: hidden;"></a>
</h3>
<ul>
<li>集成 ReAct 推理框架实现自动化工具调度</li>
<li>通过系统提示词约束工具使用规范</li>
</ul>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">SYSTEM_PROMPT</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> """</span><span class="z-constant">\</span></span>
<span class="giallo-l"><span class="z-string">法律咨询必须遵循以下规则：</span></span>
<span class="giallo-l"><span class="z-string">1. 首次响应前必须调用fetch_ipinfo确认用户辖区</span></span>
<span class="giallo-l"><span class="z-string">2. 引用法律条文需标注具体条款编号</span></span>
<span class="giallo-l"><span class="z-string">3. 不得对未覆盖地区提供法律建议</span><span class="z-punctuation z-definition z-string">"""</span></span></code></pre>
<p>通过持续扩展 MCP 生态，开发者可快速构建具备专业领域能力的智能代理系统。欢迎访问 MCP 开发者社区获取更多工具资源。</p>
<p>查看源代码：https://github.com/psiace/psiac</p>
VLM 解析非结构化图像：一个极简可扩展方案
2024-11-28T00:00:00+00:00
2024-11-28T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/a-dead-simple-way-to-vlm-parsing/
<p>这篇文章展示一种非常直接的做法：用 VLM（Visual Language Models）解析图片中的非结构化信息。</p>
<p>它足够简单，但也保留了明确的扩展路径，比如继续支持 PDF、表格、视频帧等更复杂场景。</p>
<p>如果你想要一条更重型的工业化路线，可以看 <a rel="nofollow noreferrer external" href="https://www.llamaindex.ai/llamaparse">LlamaParse</a> 这类产品，它会叠加 OCR、表格解析等更多步骤。</p>
<p>我们先看一个常见场景：你有一批图片，需要抽取文字；或者你想给图片生成可检索描述，用于全文搜索。</p>
<p>这类事情，正适合交给 VLM。</p>
<p>我示例里用的是 <a rel="nofollow noreferrer external" href="https://github.com/run-llama/llama_index">llama_index</a>，但核心思路和具体框架无关，迁移到你自己的客户端也很容易。</p>
<h2 id="xian-shang-dai-ma">先上代码<a class="zola-anchor" href="#xian-shang-dai-ma" aria-label="Anchor link for: xian-shang-dai-ma" style="visibility: hidden;"></a>
</h2>
<p>第一步是定义一个明确的提示词，让模型知道输出结构和覆盖范围。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">BASIC_PROMPT</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> """</span></span>
<span class="giallo-l"><span class="z-string"> Please analyze this image comprehensively and provide the following information:</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> 1. General Overview:</span></span>
<span class="giallo-l"><span class="z-string"> - Main subject matter and content</span></span>
<span class="giallo-l"><span class="z-string"> - Overall composition and context</span></span>
<span class="giallo-l"><span class="z-string"> - Key visual elements present</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> 2. Text Content:</span></span>
<span class="giallo-l"><span class="z-string"> - Transcribe any visible text accurately</span></span>
<span class="giallo-l"><span class="z-string"> - Include headers, labels, and captions</span></span>
<span class="giallo-l"><span class="z-string"> - Note any important text formatting or emphasis</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> 3. Data Visualization (if present):</span></span>
<span class="giallo-l"><span class="z-string"> - For tables:</span></span>
<span class="giallo-l"><span class="z-string"> * Convert to markdown format</span></span>
<span class="giallo-l"><span class="z-string"> * Preserve column headers and data relationships</span></span>
<span class="giallo-l"><span class="z-string"> - For charts/graphs:</span></span>
<span class="giallo-l"><span class="z-string"> * Describe the type of visualization</span></span>
<span class="giallo-l"><span class="z-string"> * Explain key trends and patterns</span></span>
<span class="giallo-l"><span class="z-string"> * List important data points and values</span></span>
<span class="giallo-l"><span class="z-string"> - For diagrams/flowcharts:</span></span>
<span class="giallo-l"><span class="z-string"> * Explain the structure and relationships</span></span>
<span class="giallo-l"><span class="z-string"> * Describe the flow or process</span></span>
<span class="giallo-l"><span class="z-string"> * Note any important symbols or annotations</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> 4. Additional Details:</span></span>
<span class="giallo-l"><span class="z-string"> - Identify any branding or logos</span></span>
<span class="giallo-l"><span class="z-string"> - Note color schemes if significant</span></span>
<span class="giallo-l"><span class="z-string"> - Describe any relevant metadata or context</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> Please format the response clearly and maintain the original structure of any data.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span></span></code></pre>
<p>接下来是一个最小可运行的图片解析器：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> pathlib</span><span class="z-keyword"> import</span><span> Path</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> typing</span><span class="z-keyword"> import</span><span> List</span></span>
<span class="giallo-l"><span class="z-keyword">import</span><span> base64</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> io</span><span class="z-keyword"> import</span><span> BytesIO</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span class="z-constant"> PIL</span><span class="z-keyword"> import</span><span> Image</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>core</span><span>.</span><span>multi_modal_llms</span><span class="z-keyword"> import</span><span> MultiModalLLM</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>core</span><span>.</span><span>multi_modal_llms</span><span>.</span><span>generic_utils</span><span class="z-keyword"> import</span><span> ImageDocument</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> SimpleImageParser</span><span>:</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-support"> __init__</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> model</span><span>:</span><span> MultiModalLLM</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>model</span><span class="z-keyword"> =</span><span> model</span></span>
<span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>prompt</span><span class="z-keyword"> =</span><span class="z-constant"> BASIC_PROMPT</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span><span class="z-string">A simple parser for extracting information from images using VLMs.</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string"> Args:</span></span>
<span class="giallo-l"><span class="z-string"> model (MultiModalLLM): The multi-modal language model to use for parsing</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> process_image</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> image_path</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -></span><span class="z-support"> str</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span><span class="z-string">Convert image to base64 encoding</span><span class="z-punctuation z-definition z-string">"""</span></span>
<span class="giallo-l"><span> image</span><span class="z-keyword"> =</span><span> Image</span><span>.</span><span>open</span><span>(</span><span>image_path</span><span>)</span></span>
<span class="giallo-l"><span> buffered</span><span class="z-keyword"> =</span><span> BytesIO</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span> image</span><span>.</span><span>save</span><span>(</span><span>buffered</span><span>,</span><span class="z-variable"> format</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">PNG</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> base64</span><span>.</span><span>b64encode</span><span>(</span><span>buffered</span><span>.</span><span>getvalue</span><span>(</span><span>)</span><span>)</span><span>.</span><span>decode</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">utf-8</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type"> async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> parse</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> image_path</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -></span><span class="z-support"> str</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> """</span><span class="z-string">Parse image content</span><span class="z-punctuation z-definition z-string">"""</span></span>
<span class="giallo-l"><span> image_data</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>process_image</span><span>(</span><span>image_path</span><span>)</span></span>
<span class="giallo-l"><span> image_doc</span><span class="z-keyword"> =</span><span> ImageDocument</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> image_url</span><span class="z-keyword">=</span><span class="z-storage z-type">f</span><span class="z-string">"</span><span class="z-string">data:image/jpeg;base64,</span><span class="z-constant">{</span><span>image_data</span><span class="z-constant">}</span><span class="z-string">"</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"><span> response</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-language"> self</span><span>.</span><span>model</span><span>.</span><span>acomplete</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> prompt</span><span class="z-keyword">=</span><span class="z-variable z-language">self</span><span>.</span><span>prompt</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> image_documents</span><span class="z-keyword">=</span><span>[</span><span>image_doc</span><span>]</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> str</span><span>(</span><span>response</span><span>)</span></span></code></pre>
<p>核心只有两步：</p>
<ol>
<li>把图片转成 base64。</li>
<li>作为 <code>image_documents</code> 传给 VLM。</li>
</ol>
<h2 id="pao-yi-quan">跑一圈<a class="zola-anchor" href="#pao-yi-quan" aria-label="Anchor link for: pao-yi-quan" style="visibility: hidden;"></a>
</h2>
<p>下面是如何使用这个解析器：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> asyncio</span></span>
<span class="giallo-l"><span class="z-keyword">import</span><span> os</span></span>
<span class="giallo-l"><span class="z-keyword">import</span><span> argparse</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> pathlib</span><span class="z-keyword"> import</span><span> Path</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> llama_index</span><span>.</span><span>multi_modal_llms</span><span>.</span><span>openai</span><span class="z-keyword"> import</span><span> OpenAIMultiModal</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> dotenv</span><span class="z-keyword"> import</span><span> load_dotenv</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>load_dotenv</span><span>(</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> main</span><span>(</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> parser</span><span class="z-keyword"> =</span><span> argparse</span><span>.</span><span>ArgumentParser</span><span>(</span><span class="z-variable">description</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Parse image content</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span> parser</span><span>.</span><span>add_argument</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">image_path</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> type</span><span class="z-keyword">=</span><span class="z-support">str</span><span>,</span><span class="z-variable"> help</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Path to the image file</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span> args</span><span class="z-keyword"> =</span><span> parser</span><span>.</span><span>parse_args</span><span>(</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span> image_path</span><span class="z-keyword"> =</span><span> Path</span><span>(</span><span>args</span><span>.</span><span>image_path</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> image_path</span><span>.</span><span>exists</span><span>(</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">"</span><span class="z-string">Image file does not exist: </span><span class="z-constant">{</span><span>image_path</span><span class="z-constant">}</span><span class="z-string">"</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Initialize the VLM</span></span>
<span class="giallo-l"><span> model</span><span class="z-keyword"> =</span><span> OpenAIMultiModal</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> model</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>getenv</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">MULTI_MODAL_LLM_MODEL</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">gpt-4o-mini</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> api_key</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>getenv</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">MULTI_MODAL_LLM_API_KEY</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> api_base</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>getenv</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">MULTI_MODAL_LLM_API_BASE</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">https://api.openai.com/v1</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> max_new_tokens</span><span class="z-keyword">=</span><span class="z-support">int</span><span>(</span><span>os</span><span>.</span><span>getenv</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">MULTI_MODAL_LLM_MAX_TOKENS</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">512</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> temperature</span><span class="z-keyword">=</span><span class="z-support">float</span><span>(</span><span>os</span><span>.</span><span>getenv</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">MULTI_MODAL_LLM_TEMPERATURE</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">0.7</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> verbose</span><span class="z-keyword">=</span><span>os</span><span>.</span><span>getenv</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">MULTI_MODAL_LLM_VERBOSE</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">False</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>.</span><span>lower</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">true</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span> )</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Create parser and parse image</span></span>
<span class="giallo-l"><span> parser</span><span class="z-keyword"> =</span><span> SimpleImageParser</span><span>(</span><span>model</span><span>)</span></span>
<span class="giallo-l"><span> result</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span> parser</span><span>.</span><span>parse</span><span>(</span><span class="z-support">str</span><span>(</span><span>image_path</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span class="z-support"> print</span><span>(</span><span>result</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">if</span><span class="z-support z-variable"> __name__</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">__main__</span><span class="z-punctuation z-definition z-string">"</span><span>:</span></span>
<span class="giallo-l"><span> asyncio</span><span>.</span><span>run</span><span>(</span><span>main</span><span>(</span><span>)</span><span>)</span></span></code></pre>
<p>这段代码会初始化 VLM，创建解析器，然后输出解析结果。</p>
<h2 id="yun-xing-demo">运行 Demo<a class="zola-anchor" href="#yun-xing-demo" aria-label="Anchor link for: yun-xing-demo" style="visibility: hidden;"></a>
</h2>
<p>完整示例代码在这里：</p>
<ul>
<li><a rel="nofollow noreferrer external" href="https://github.com/psiace/psiace/tree/main/demo/vlm-parsing">psiace/demo/vlm-parsing</a></li>
</ul>
<p>运行方式：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">python</span><span class="z-string"> basic.py</span><span class="z-keyword"> <</span><span class="z-string">image_pat</span><span>h</span><span class="z-keyword">></span></span></code></pre>
<p>示例图片是一张家庭网关界面截图（来源：<a rel="nofollow noreferrer external" href="https://commons.wikimedia.org/wiki/File:Home_gateway_example.png">Home gateway example</a>）：</p>
<p><img src="https://psiace.me/zh/posts/a-dead-simple-way-to-vlm-parsing/example.png" alt="Home gateway example" /></p>
<p>终端中的解析输出示例：</p>
<p><img src="https://psiace.me/zh/posts/a-dead-simple-way-to-vlm-parsing/example-result.png" alt="Home gateway example result" /></p>
<h2 id="bonus-ru-he-kuo-zhan-zhe-ge-parser">Bonus：如何扩展这个 Parser<a class="zola-anchor" href="#bonus-ru-he-kuo-zhan-zhe-ge-parser" aria-label="Anchor link for: bonus-ru-he-kuo-zhan-zhe-ge-parser" style="visibility: hidden;"></a>
</h2>
<p>下面是几个实用扩展方向：</p>
<ol>
<li><strong>格式支持</strong></li>
</ol>
<ul>
<li>用 <code>pdf2image</code> 处理 PDF。</li>
<li>用 <code>opencv-python</code> 抽取视频帧后再解析。</li>
</ul>
<ol start="2">
<li><strong>输出形态</strong></li>
</ol>
<ul>
<li>增加 JSON 输出：</li>
</ul>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">async</span><span class="z-storage z-type"> def</span><span class="z-entity z-name"> parse_to_json</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> image_path</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -></span><span class="z-support"> dict</span><span>:</span></span>
<span class="giallo-l"><span> result</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-language"> self</span><span>.</span><span>parse</span><span>(</span><span>image_path</span><span>)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Add your JSON transformation logic here</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> json_result</span></span></code></pre>
<ul>
<li>用 Jinja2 等模板工具生成更稳定的结构化文本。</li>
</ul>
<ol start="3">
<li><strong>处理流水线</strong></li>
</ol>
<ul>
<li>接入 Tesseract OCR 做文字前处理。</li>
<li>追加表格解析能力。</li>
<li>用 asyncio 做批处理。</li>
</ul>
<ol start="4">
<li><strong>系统集成</strong></li>
</ol>
<ul>
<li>接入 llama-index 做 RAG。</li>
<li>进一步封装成自动化工作流。</li>
</ul>
<h2 id="resources">Resources<a class="zola-anchor" href="#resources" aria-label="Anchor link for: resources" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="nofollow noreferrer external" href="https://docs.llamaindex.ai/">llama-index Documentation</a></li>
<li><a rel="nofollow noreferrer external" href="https://platform.openai.com/">OpenAI</a></li>
<li><a rel="nofollow noreferrer external" href="https://pillow.readthedocs.io/">PIL (Python Imaging Library)</a></li>
</ul>
<hr />
<p>如果你只想快速验证“VLM 解析图片”是否有业务价值，这个极简方案足够开始。</p>
<p>先跑通最小闭环，再决定是否引入 OCR、表格结构化和更复杂的工程管线。</p>
别急着招 DevRel
2024-03-08T00:00:00+00:00
2024-03-08T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/you-do-not-need-the-fucking-devrel/
<h2 id="xian-bie-da-yan-gao-pai">先别打广告牌<a class="zola-anchor" href="#xian-bie-da-yan-gao-pai" aria-label="Anchor link for: xian-bie-da-yan-gao-pai" style="visibility: hidden;"></a>
</h2>
<p>很多团队把 DevRel 想成会写文案、会上台、能在社交媒体刷存在感的“吉祥物”。真要这样，不如直接买块广告牌，或者训练一只会说话的鹦鹉。DevRel 如果只是扩音器，迟早会在会议室里被当成背景音。</p>
<p>真正的 DevRel 是把产品和开发者社区连接起来的桥。从用户视角出发，帮团队把复杂的技术语言翻译成可理解、可落地的解决方案。他既要懂产品路线，也要摸得清社区脉搏；既能撸代码，也能写故事。</p>
<h2 id="san-jian-shi-xiang-qing-chu">三件事想清楚<a class="zola-anchor" href="#san-jian-shi-xiang-qing-chu" aria-label="Anchor link for: san-jian-shi-xiang-qing-chu" style="visibility: hidden;"></a>
</h2>
<h3 id="1-quan-ze-zi-yuan-yao-pi-pei">1. 权责资源要匹配<a class="zola-anchor" href="#1-quan-ze-zi-yuan-yao-pi-pei" aria-label="Anchor link for: 1-quan-ze-zi-yuan-yao-pi-pei" style="visibility: hidden;"></a>
</h3>
<p>DevRel 需要参与决策，至少要能影响产品优先级和内容走向。如果每次都被挡在“等业务拍板”之外，他说的任何话都会显得苍白。给予授权，也意味着给足资源：真实数据、工程背景、核心成员的时间。</p>
<h3 id="2-xu-shi-yao-yi-zhi">2. 叙事要一致<a class="zola-anchor" href="#2-xu-shi-yao-yi-zhi" aria-label="Anchor link for: 2-xu-shi-yao-yi-zhi" style="visibility: hidden;"></a>
</h3>
<p>让 DevRel 深入团队，把一线的设计取舍、踩坑记录都吸纳进来。只有这样，他们写出来的内容才像亲历者——不是新闻稿，也不是照本宣科的教程，而是能回答“为什么值得一试”这样的疑问。</p>
<h3 id="3-cheng-ken-bi-xing-shi-geng-nan">3. 诚恳比形式更难<a class="zola-anchor" href="#3-cheng-ken-bi-xing-shi-geng-nan" aria-label="Anchor link for: 3-cheng-ken-bi-xing-shi-geng-nan" style="visibility: hidden;"></a>
</h3>
<p>社区对虚假的热情特别敏感。与其用堆砌的 buzzword，不如老老实实讲“我们是怎么解决 X 问题的”“我们做错过什么”。真诚是唯一的复利策略。</p>
<h2 id="shen-me-shi-hou-zan-huan">什么时候暂缓<a class="zola-anchor" href="#shen-me-shi-hou-zan-huan" aria-label="Anchor link for: shen-me-shi-hou-zan-huan" style="visibility: hidden;"></a>
</h2>
<p>如果你还没准备好让 DevRel 拿到这些权力与资源，那就别急着招人。让创始人或者资深工程师先上阵：他们说话更有分量，也更容易获得团队信任。真正需要 DevRel 的时刻，是你想把这套叙事机制变成常态的时候。</p>
<p>DevRel 永远不是灵丹妙药。它是一种长期投入，需要团队，把“讲清楚”和“做得好”同时放在心上。</p>
A New Beginning, with Astro
2023-09-25T00:00:00+00:00
2023-09-25T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/a-new-beginning/
<blockquote>
<p><em>中文翻译正在整理，以下为英文原文。</em></p>
</blockquote>
<h2 id="hey-world">Hey, World!<a class="zola-anchor" href="#hey-world" aria-label="Anchor link for: hey-world" style="visibility: hidden;"></a>
</h2>
<p>I am delighted to announce the launch of my new blog, which is powered by <a rel="nofollow noreferrer external" href="https://github.com/withastro/">Astro</a> and features the <a rel="nofollow noreferrer external" href="https://github.com/chrismwilliams/astro-theme-cactus">Astro Cactus</a> theme.</p>
<p>In this fresh start, I have cleared all previous content to create a clean slate.</p>
<h2 id="why-and-why-not">Why and Why Not?<a class="zola-anchor" href="#why-and-why-not" aria-label="Anchor link for: why-and-why-not" style="visibility: hidden;"></a>
</h2>
<p>The idea of starting anew had been on my mind for a few months, but it was my recent conversation with <a rel="nofollow noreferrer external" href="https://github.com/xuanwo">@Xuanwo</a> that finally pushed me to take action.</p>
<p>There are numerous reasons behind this decision:</p>
<blockquote>
<p>I aspire to connect with a broader audience and have a more significant impact.</p>
</blockquote>
<blockquote>
<p>I aim to express my insights more effectively, moving beyond mere documentation of events.</p>
</blockquote>
<p>However, in reality, the decision was not driven by extensive contemplation; it was simply a matter of “Why not?”</p>
<p>Striving to do my best is sufficient.</p>
<hr />
<p>I hope you’ll join me on this exciting journey!</p>
Apache OpenDAL (Incubating) ：无痛数据访问新体验
2023-07-05T00:00:00+00:00
2023-07-05T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/apache-opendal/
<blockquote>
<p>本文主要根据 <a rel="nofollow noreferrer external" href="https://note.xuanwo.io/#/page/opendal%2F%E9%9D%A2%E5%90%91%20java%20%E7%94%A8%E6%88%B7%E7%9A%84%E4%BB%8B%E7%BB%8D">面向 Java 用户的介绍 | @Xuanwo</a> 整理而来。</p>
</blockquote>
<p>如果你致力于构建云原生、跨云优先的应用程序及服务，或者希望支持可配置的存储后端以满足复杂的数据访问需要，再或者，你厌倦了在各种 SDK 中进行周旋并期待一个统一的抽象与开发体验，Apache OpenDAL (Incubating) 将会是你的绝佳拍档。</p>
<p><img src="https://psiace.me/zh/posts/apache-opendal/apache-opendal.png" alt="Apache OpenDAL (Incubating) Arch" /></p>
<h2 id="opendal-shi-shen-me">OpenDAL 是什么<a class="zola-anchor" href="#opendal-shi-shen-me" aria-label="Anchor link for: opendal-shi-shen-me" style="visibility: hidden;"></a>
</h2>
<p>OpenDAL 是一个数据访问层，允许用户以统一的方式轻松有效地从各种存储服务中检索数据。</p>
<p><strong>数据访问层</strong> 意味着：OpenDAL 在数据读写流程中处于一个 <strong>承上启下</strong> 的关键位置，我们屏蔽了不同存储后端的实现细节，对外提供了一套统一的接口抽象。</p>
<p>接下来，让我们试着回答「OpenDAL 不是什么」，从另一个角度来解构 OpenDAL ：</p>
<h3 id="opendal-bu-shi-dai-li-fu-wu">OpenDAL 不是代理服务<a class="zola-anchor" href="#opendal-bu-shi-dai-li-fu-wu" aria-label="Anchor link for: opendal-bu-shi-dai-li-fu-wu" style="visibility: hidden;"></a>
</h3>
<p>OpenDAL 以库的形式提供，而并非代理各种存储后端的服务或应用。</p>
<p>如果你希望将 OpenDAL 集成到现有项目中，需要通过 OpenDAL 支持的语言来调用 OpenDAL 的接口直接访问存储服务。</p>
<h3 id="opendal-bu-shi-sdk-ju-he-qi">OpenDAL 不是 SDK 聚合器<a class="zola-anchor" href="#opendal-bu-shi-sdk-ju-he-qi" aria-label="Anchor link for: opendal-bu-shi-sdk-ju-he-qi" style="visibility: hidden;"></a>
</h3>
<p>尽管 OpenDAL 取代了各类 SDK 在应用架构中的生态位，但 OpenDAL 并不是以 SDK 聚合器的形式进行实现。</p>
<p>换句话说，OpenDAL 不是简单的调用各个存储服务的 SDK，我们基于统一的 Rust 核心开发自行实现了各个存储服务的对接，确保抹平服务之间的细节差异。</p>
<p>以 S3 为例，OpenDAL 手动构造 HTTP Request 并解析 HTTP Response，保证所有行为都符合 API 规范并且完全纳入 OpenDAL 的掌控之中。得益于 OpenDAL 以原生形式接管数据访问流程，我们可以轻松为各种存储后端实现统一的重试和日志机制，并确保行为的一致性。</p>
<p>而对于 S3 的兼容服务，由于原生存储服务的限制和 API 实现的差异，兼容程度和行为细节都可能会与 S3 存在差异，比如 OSS 对 Range 的默认实现就需要设置一个独立的 Header 才能确保行为一致。OpenDAL 除了对接原生存储服务之外，也会对兼容性服务进行针对性处理，以确保用户的数据访问体验。</p>
<h2 id="opendal-de-you-shi">OpenDAL 的优势<a class="zola-anchor" href="#opendal-de-you-shi" aria-label="Anchor link for: opendal-de-you-shi" style="visibility: hidden;"></a>
</h2>
<p>OpenDAL 并不是唯一一个致力于提供数据访问抽象的项目，但相比于其他同类项目，OpenDAL 具有如下优势：</p>
<h3 id="feng-fu-de-fu-wu-zhi-chi">丰富的服务支持<a class="zola-anchor" href="#feng-fu-de-fu-wu-zhi-chi" aria-label="Anchor link for: feng-fu-de-fu-wu-zhi-chi" style="visibility: hidden;"></a>
</h3>
<ul>
<li>OpenDAL 支持数十种存储服务，覆盖场景全面，支持按需选用：
<ul>
<li>标准存储协议：FTP，HTTP，SFTP，WebDAV 等</li>
<li>对象存储服务：azblob，gcs，obs，oss，s3 等</li>
<li>文件存储服务：fs, azdfs，hdfs，webhdfs, ipfs 等</li>
<li>消费级存储服务（网盘）：Google Drive，OneDrive，Dropbox 等</li>
<li>Key Value 存储服务：Memory，Redis，Rocksdb 等</li>
<li>缓存服务：Ghac，Memcached 等</li>
</ul>
</li>
</ul>
<h3 id="wan-zheng-de-kua-yu-yan-bang-ding">完整的跨语言绑定<a class="zola-anchor" href="#wan-zheng-de-kua-yu-yan-bang-ding" aria-label="Anchor link for: wan-zheng-de-kua-yu-yan-bang-ding" style="visibility: hidden;"></a>
</h3>
<ul>
<li>以 Rust 为核心，OpenDAL 现在提供 Python/Node.js/Java/C 等多个语言的绑定支持，同时也在积极开发其他语言的绑定。</li>
<li>跨语言绑定不光为其他语言提供统一的存储访问抽象，设计和实现上也尽可能遵循各种语言约定俗成的命名风格和开发习惯，为快速上手使用铺平道路。</li>
</ul>
<h3 id="qiang-da-de-zhong-jian-jian-zhi-chi">强大的中间件支持<a class="zola-anchor" href="#qiang-da-de-zhong-jian-jian-zhi-chi" aria-label="Anchor link for: qiang-da-de-zhong-jian-jian-zhi-chi" style="visibility: hidden;"></a>
</h3>
<ul>
<li>OpenDAL 提供原生的中间件能力，主要包括
<ul>
<li>错误重试：OpenDAL 支持细粒度的错误重试能力，除了常见的请求重试之外，支持从断点续传，不需要重新读取整个文件。</li>
<li>可观测性支持：OpenDAL 对所有操作都实现了 logging，tracing，metrics 支持，开启中间件就能直接获得对存储的可观测性能力。</li>
<li>此外还有并发控制，流控，模糊测试等。</li>
</ul>
</li>
</ul>
<h3 id="jian-dan-yi-yong">简单易用<a class="zola-anchor" href="#jian-dan-yi-yong" aria-label="Anchor link for: jian-dan-yi-yong" style="visibility: hidden;"></a>
</h3>
<ul>
<li>
<p>OpenDAL 的 API 经过良好的设计并在实际使用中不断打磨，文档覆盖全面，方便快速上手。下面是一个使用 Python 绑定访问 HDFS 的例子：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> opendal</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>op</span><span class="z-keyword"> =</span><span> opendal</span><span>.</span><span>Operator</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">hdfs</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-variable"> name_node</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">hdfs://192.16.8.10.103</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span>
<span class="giallo-l"><span>op</span><span>.</span><span>read</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">path/to/file</span><span class="z-punctuation z-definition z-string">"</span><span>)</span></span></code></pre></li>
</ul>
<h3 id="opendal-de-shi-yong-chang-jing">OpenDAL 的使用场景<a class="zola-anchor" href="#opendal-de-shi-yong-chang-jing" aria-label="Anchor link for: opendal-de-shi-yong-chang-jing" style="visibility: hidden;"></a>
</h3>
<p>目前 OpenDAL 被广泛应用于有云原生需要的各种场景，包括但不限于数据库、数据管道和缓存等，主要用户案例包括：</p>
<ul>
<li>Databend：OLAP 云原生数据仓库，使用 OpenDAL 来读写持久化数据（s3，azblob，gcs，hdfs 等）和缓存数据（fs，redis，rocksdb，moka 等）</li>
<li>GreptimeDB：云原生时序数据库，使用 OpenDAL 来读写持久化数据（s3，azblob 等）</li>
<li>RisingWave：用于流处理的分布式 SQL 数据库，使用 OpenDAL 来读写持久化数据 （s3，azblob，hdfs 等）</li>
<li>Vector: 可观察性数据管道，使用 OpenDAL 来写入持久化数据（目前以 hdfs 的使用为主）</li>
<li>Sccache：支持云存储的类 ccache 工具，主要用于缓存 rust/cpp 语言的编译产物，使用 OpenDAL 来读写缓存数据（s3 和 ghac 等）</li>
</ul>
<h2 id="opendal-de-wei-lai-gui-hua">OpenDAL 的未来规划<a class="zola-anchor" href="#opendal-de-wei-lai-gui-hua" aria-label="Anchor link for: opendal-de-wei-lai-gui-hua" style="visibility: hidden;"></a>
</h2>
<p>除了进一步满足云原生数据访问需求之外，OpenDAL 将会持续拓展用户场景，积极探索在数据科学、移动应用等方面的使用。同时，OpenDAL 也会持续打磨现有的实现和绑定，为用户提供更好的集成体验。</p>
<p>OpenDAL 还将会探索如何改善用户在数据管理和服务集成的工作流：</p>
<ul>
<li>打磨 oli 命令行工具，帮助用户无痛管理数据。</li>
<li>实现 oay 代理服务，为用户提供高质量的兼容 API 。</li>
</ul>
<p>另外，由于 OpenDAL 目前是一个跨多语言的项目，我们还计划撰写一系列入门教程，帮助大家从 0 开始，在学习语言的同时掌握 OpenDAL 的使用技巧。</p>
<h2 id="zhi-xie">致谢<a class="zola-anchor" href="#zhi-xie" aria-label="Anchor link for: zhi-xie" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="nofollow noreferrer external" href="https://opendal.apache.org/">Apache OpenDAL(Incubating) | Website</a></li>
<li><a rel="nofollow noreferrer external" href="https://github.com/apache/incubator-opendal">apache/incubator-opendal | GitHub</a></li>
<li><a rel="nofollow noreferrer external" href="https://note.xuanwo.io/#/page/opendal%2F%E9%9D%A2%E5%90%91%20java%20%E7%94%A8%E6%88%B7%E7%9A%84%E4%BB%8B%E7%BB%8D">面向 Java 用户的介绍 | @Xuanwo</a></li>
</ul>
我永远讨厌 Python Fibonacci
2022-09-30T00:00:00+00:00
2022-09-30T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/master-python-fibonacci/
<p>这里是 PsiACE，好久没和大家见面做公开的汇报了。</p>
<p>目前的话人在澳门，总体上还不错，最近一段时间做饭水平急速提高，并且不得不捡起好久没写过的 Python 。</p>
<p>「回」字大概有四种写法，Python Fibonacci 则更多，让我们一起来看一下吧。</p>
<p>这篇文章主要从两个方面来介绍，前半部分主要关注 Fibonacci 的不同算法实现，后半部分则会关注如何使用 C/C++ 等来拓展 Fibonacci 。</p>
<h2 id="fibonacci-de-bu-tong-suan-fa-shi-xian">Fibonacci 的不同算法实现<a class="zola-anchor" href="#fibonacci-de-bu-tong-suan-fa-shi-xian" aria-label="Anchor link for: fibonacci-de-bu-tong-suan-fa-shi-xian" style="visibility: hidden;"></a>
</h2>
<p><a rel="nofollow noreferrer external" href="https://link.zhihu.com/?target=https%3A//en.wikipedia.org/wiki/Fibonacci%23Fibonacci_sequence">斐波那契数列</a>（Fibonacci sequence）是以意大利数学家 <code>列昂纳多·斐波那契</code> 的名字命名的数列。</p>
<p>斐波那契数列在计算机里面有很多用途，例如斐波那契查找（二分查找的一种改进），斐波那契堆等。</p>
<h3 id="di-gui">递归<a class="zola-anchor" href="#di-gui" aria-label="Anchor link for: di-gui" style="visibility: hidden;"></a>
</h3>
<p>根据 Fibonacci 定义，可以轻松写出一个递归算法：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> <=</span><span class="z-constant"> 1</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> n</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span></code></pre><h3 id="ji-yi-hua">记忆化<a class="zola-anchor" href="#ji-yi-hua" aria-label="Anchor link for: ji-yi-hua" style="visibility: hidden;"></a>
</h3>
<p>一个简单的优化思路是采用记忆化，因为是一个递归的计算方法，保存之前的结果会比较有利。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">lru_cache</span><span>(</span><span>)</span></span>
<span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> <=</span><span class="z-constant"> 1</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> n</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> fib</span><span>(</span><span>n</span><span>)</span></span></code></pre>
<p>进一步优化的话可以选择递推形式的算法，比如记忆全部的前置结果。大概是线性级别。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> data</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>]</span></span>
<span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>n</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> data</span><span>.</span><span>append</span><span>(</span><span>data</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> +</span><span> data</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> data</span><span>[</span><span>n</span><span>]</span></span></code></pre>
<p>但是事实上，我们不需要记录那么多中间结果，仅需要保留前两个值即可：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> a</span><span>,</span><span> b</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span></span>
<span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> a</span><span>,</span><span> b</span><span class="z-keyword"> =</span><span> b</span><span>,</span><span> a</span><span class="z-keyword"> +</span><span> b</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> a</span></span></code></pre><h3 id="shu-xue">数学<a class="zola-anchor" href="#shu-xue" aria-label="Anchor link for: shu-xue" style="visibility: hidden;"></a>
</h3>
<p>更进一步地，如果将其递推公式整理为通项公式，可以得到下面的算法：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> sqrt5</span><span class="z-keyword"> =</span><span class="z-constant"> 5</span><span class="z-keyword">**</span><span class="z-constant">0.5</span></span>
<span class="giallo-l"><span> fibN</span><span class="z-keyword"> =</span><span> (</span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> +</span><span> sqrt5</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 2</span><span>)</span><span class="z-keyword"> **</span><span> n</span><span class="z-keyword"> -</span><span> (</span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> -</span><span> sqrt5</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 2</span><span>)</span><span class="z-keyword"> **</span><span> n</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> round</span><span>(</span><span>fibN</span><span class="z-keyword"> /</span><span> sqrt5</span><span>)</span></span></code></pre>
<p>这种方法非常快，但是要考虑 <code>int</code> 溢出，仅仅对小数据量有效。(常数级别)</p>
<h3 id="ju-zhen-cheng-fa">矩阵乘法<a class="zola-anchor" href="#ju-zhen-cheng-fa" aria-label="Anchor link for: ju-zhen-cheng-fa" style="visibility: hidden;"></a>
</h3>
<p>那么还有没有其他方法呢？比如矩阵乘法，大概是对数级别：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> <</span><span class="z-constant"> 2</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> n</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span> q</span><span class="z-keyword"> =</span><span> [</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>,</span><span> [</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 0</span><span>]</span><span>]</span></span>
<span class="giallo-l"><span> res</span><span class="z-keyword"> =</span><span> matrix_pow</span><span>(</span><span>q</span><span>,</span><span> n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> res</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span class="z-constant">0</span><span>]</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> matrix_pow</span><span>(</span><span class="z-variable z-parameter z-function">a</span><span>,</span><span class="z-variable z-parameter z-function"> n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> ret</span><span class="z-keyword"> =</span><span> [</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 0</span><span>]</span><span>,</span><span> [</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>]</span></span>
<span class="giallo-l"><span class="z-keyword"> while</span><span> n</span><span class="z-keyword"> ></span><span class="z-constant"> 0</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> &</span><span class="z-constant"> 1</span><span>:</span></span>
<span class="giallo-l"><span> ret</span><span class="z-keyword"> =</span><span> matrix_multiply</span><span>(</span><span>ret</span><span>,</span><span> a</span><span>)</span></span>
<span class="giallo-l"><span> n</span><span class="z-keyword"> >>=</span><span class="z-constant"> 1</span></span>
<span class="giallo-l"><span> a</span><span class="z-keyword"> =</span><span> matrix_multiply</span><span>(</span><span>a</span><span>,</span><span> a</span><span>)</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> ret</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> matrix_multiply</span><span>(</span><span class="z-variable z-parameter z-function">a</span><span>,</span><span class="z-variable z-parameter z-function"> b</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> c</span><span class="z-keyword"> =</span><span> [</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>]</span><span>,</span><span> [</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>]</span><span>]</span></span>
<span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">2</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> for</span><span> j</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">2</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span> c</span><span>[</span><span>i</span><span>]</span><span>[</span><span>j</span><span>]</span><span class="z-keyword"> =</span><span> a</span><span>[</span><span>i</span><span>]</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> *</span><span> b</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span>j</span><span>]</span><span class="z-keyword"> +</span><span> a</span><span>[</span><span>i</span><span>]</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> *</span><span> b</span><span>[</span><span class="z-constant">1</span><span>]</span><span>[</span><span>j</span><span>]</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> c</span></span></code></pre><h2 id="shi-yong-c-c-tuo-zhan-fibonacci">使用 C / C++ 拓展 Fibonacci<a class="zola-anchor" href="#shi-yong-c-c-tuo-zhan-fibonacci" aria-label="Anchor link for: shi-yong-c-c-tuo-zhan-fibonacci" style="visibility: hidden;"></a>
</h2>
<p>一个非常典型的观点是，Python是一种适合初学者、开发快速的语言，但没有很大的性能优势。甚至在 PyCon 上，<a rel="nofollow noreferrer external" href="https://github.com/gvanrossum">@gvanrossum</a> 也说，必须让 Python 语言的速度水平提高 2 倍，借此与 C++ 等高性能编程语言正面对抗。</p>
<p>显然，存在一些已知的改善性能的办法，并且在主流的数据科学包以及 web framework 包中得到了应用。</p>
<ul>
<li>降低时间复杂度。不管是什么原因导致程序变慢，只要可以，直接选择一个更快的算法。</li>
<li>并行化代码。如果存在多个闲置的处理器，可以尝试将任务分割成可以同时处理的子任务。</li>
<li>使用更快的语言重写代码中较慢的部分。</li>
</ul>
<p>使用 C / C++ 拓展 Python 的显著好处：</p>
<ul>
<li>一方面，得益于 Python 的简单易用，可以提供一套清晰和简化的接口，降低下游开发人员的精力投入，加速应用的开发。</li>
<li>另一方面，得益于其他语言的性能和编译优化，可以显著改善程序性能。</li>
</ul>
<h3 id="ru-he-shi-yong-c-c-tuo-zhan-python">如何使用 C / C++ 拓展 Python<a class="zola-anchor" href="#ru-he-shi-yong-c-c-tuo-zhan-python" aria-label="Anchor link for: ru-he-shi-yong-c-c-tuo-zhan-python" style="visibility: hidden;"></a>
</h3>
<p><strong>使用 Python 的 ctypes 模块</strong></p>
<p>ctypes 是 Python 官方提供的 FFI 模块，适用于动态链接库。调用时的处理复杂度基本转移到 Python，无法很好利用 Python 中的一些能力。</p>
<p><strong>使用 Python CAPI</strong></p>
<p>CPython 为 C / C++ 提供了一套 API ，可以使用 Python 原生的一些能力完成 C / C++ 与 Python 的交互。但是在调试方面依然需要采用 C / C++ 工具链，而且因为调用了 Python 底层的 CAPI，有时候需要手动去操控 Python 的引用计数来完成 Python 的 GC 机制。</p>
<p><strong>使用 Cython</strong></p>
<p>Cython 是一种面向 Python 和 Cython 语言的一个优化过的静态编译器。Cython 会将 Python 和 Cython 翻译成 C/C++，然后编译成一个静态链接库供 Python 使用。</p>
<p>Cython 除了提供 CAPI 之外，还提供了大部分的封装好的模块和函数，而对于 Unicode 或者 Python 的异常机制，Cython 会帮助你自动翻译成 C/C++ 。由于 Cython 做的是代码转译，粒度相对较粗，所以无法做一些细粒度优化。</p>
<p><strong>使用 SWIG</strong></p>
<p>SWIG 并不只是提供 C/C++ 对 Python 的拓展，还提供对 Java、Perl 等其他语言的拓展支持，就是写一个拓展可以在多处使用。</p>
<p>使用 SWIG 的最大优点是可以使同一套代码拓展多种语言，但是对于某些特性，依然还是要针对 Python 在配置文件中显式地写出一些 Python CAPI 相关的调用，在调试方面，也是只能使用 C/C++ 配套的调试工具。</p>
<h3 id="shi-li-yu-xing-neng">示例与性能<a class="zola-anchor" href="#shi-li-yu-xing-neng" aria-label="Anchor link for: shi-li-yu-xing-neng" style="visibility: hidden;"></a>
</h3>
<p>让我们继续回到斐波那契数列的例子，之前的内容中，我们曾经讨论过它的算法和一些优化。</p>
<p><strong>递归</strong></p>
<p>接下来的内容中，将会使用递归算法作为基准来展现不同的优化，除了并行部分之外，我们将会使用 <code>fib(47)</code> 进行性能评估。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> <=</span><span class="z-constant"> 1</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> n</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span></code></pre>
<p><strong>并行</strong></p>
<p>通过使用 multiprocessing 进行池化，我们得以同时执行多个计算任务，这使得在一些特定场景下具有性能优势。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> multiprocessing</span></span>
<span class="giallo-l"><span class="z-keyword">import</span><span> multiprocessing</span><span class="z-keyword"> as</span><span> mp</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment">function for calculate fibannaci number</span></span>
<span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> <=</span><span class="z-constant"> 1</span><span>:</span><span class="z-keyword"> return</span><span class="z-constant"> 1</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> parallel_fib</span><span>(</span><span class="z-variable z-parameter z-function">x</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> paralleing throught pool.</span></span>
<span class="giallo-l"><span> p</span><span class="z-keyword"> =</span><span> multiprocessing</span><span>.</span><span>Pool</span><span>(</span><span>mp</span><span>.</span><span>cpu_count</span><span>(</span><span>)</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> p</span><span>.</span><span>map</span><span>(</span><span>fib</span><span>,</span><span> [</span><span>x</span><span>,</span><span> x</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span> x</span><span class="z-keyword">+</span><span class="z-constant">2</span><span>,</span><span> x</span><span class="z-keyword">+</span><span class="z-constant">3</span><span>]</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> One-time parallel calculation</span></span>
<span class="giallo-l"><span class="z-support">print</span><span>(</span><span>parallel_fib</span><span>(</span><span class="z-constant">30</span><span>)</span><span>)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Recursive calculation one by one</span></span>
<span class="giallo-l"><span class="z-support">print</span><span>(</span><span>fib</span><span>(</span><span class="z-constant">30</span><span>)</span><span>,</span><span> fib</span><span>(</span><span class="z-constant">31</span><span>)</span><span>,</span><span> fib</span><span>(</span><span class="z-constant">32</span><span>)</span><span>,</span><span> fib</span><span>(</span><span class="z-constant">33</span><span>)</span><span>)</span></span></code></pre>
<p>简单看一下性能：</p>
<table><thead><tr><th>Language</th><th>Time, s</th></tr></thead><tbody>
<tr><td>Python Recursive</td><td>1.377</td></tr>
<tr><td>Python Parallel</td><td>0.669</td></tr>
</tbody></table>
<p><strong>快速算法 - 记忆化</strong></p>
<p>递归算法相当朴素，也非常的慢，更加快速的算法我们在之前有过讨论，这里给出一个缓存最近结果的一个简单算法。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> functools</span><span class="z-keyword"> import</span><span> lru_cache</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name">@</span><span class="z-entity z-name">lru_cache</span><span>(</span><span class="z-constant">3</span><span>)</span></span>
<span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> <=</span><span class="z-constant"> 1</span><span>:</span><span class="z-keyword"> return</span><span class="z-constant"> 1</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-support">print</span><span>(</span><span>fib</span><span>(</span><span class="z-constant">47</span><span>)</span><span>)</span></span></code></pre>
<p><strong>PyPy - JIT</strong></p>
<p>PyPy 是 CPython 的替代品。它是使用与之共同开发的 RPython 语言构建的。使用它而不是 CPython 的主要原因是速度: 它通常运行得更快。</p>
<p>PyPy 实现了 Python 2.7.18和3.7.10。它支持所有的核心语言，通过 Python 2.7 测试套件和几乎所有的 3.7 测试套件。它支持大多数常用的 Python 标准库模块。</p>
<p>PyPy 快速的秘密在于使用了 JIT 技术，以下是 JIT 编译为提高性能而采取的步骤：</p>
<ul>
<li>标识代码中最常用的组件，例如循环中的函数。</li>
<li>在运行时将这些组件转换为机器码。</li>
<li>优化生成的机器码。</li>
<li>用优化的机器码版本替换以前的实现。</li>
</ul>
<p>很高兴，我们的递归版本可以自然地利用 PyPy 进行编译以获得性能上的提升。</p>
<p><strong>C</strong></p>
<p>由于要展示 C/C++ 拓展的能力，我们也提供 C 语言版本做一个比较。</p>
<pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> <</span><span class="z-string">stdio.h</span><span class="z-punctuation z-definition z-string">></span></span>
<span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> <</span><span class="z-string">stdint.h</span><span class="z-punctuation z-definition z-string">></span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage">static</span><span class="z-storage z-type"> uint64_t</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-storage z-type">uint64_t</span><span class="z-variable"> n</span><span>)</span><span> {</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>n </span><span class="z-keyword"><=</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> return</span><span> n</span><span>;</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> fib</span><span>(</span><span>n </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span class="z-entity z-name"> fib</span><span>(</span><span>n </span><span class="z-keyword">-</span><span class="z-constant"> 2</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">int</span><span class="z-entity z-name"> main</span><span>(</span><span class="z-storage z-type">void</span><span>)</span><span> {</span></span>
<span class="giallo-l"><span class="z-entity z-name"> printf</span><span>(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-constant">%llu</span><span class="z-constant"> \n</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-entity z-name"> fib</span><span>(</span><span class="z-constant">47</span><span>)</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span><span>;</span></span>
<span class="giallo-l"><span>}</span></span></code></pre>
<p><strong>ctypes</strong></p>
<p>同样的，我们仿照之前的 C 语言版本，编写对应的共享库。</p>
<pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span class="z-keyword">%</span><span class="z-keyword">%</span><span>file fib</span><span class="z-keyword">-</span><span>share.h</span></span>
<span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> <</span><span class="z-string">stdint.h</span><span class="z-punctuation z-definition z-string">></span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">uint64_t</span><span class="z-entity z-name"> c_fib</span><span>(</span><span class="z-storage z-type">uint64_t</span><span class="z-variable"> n</span><span>)</span><span>;</span></span></code></pre><pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span class="z-keyword">%</span><span class="z-keyword">%</span><span>file fib</span><span class="z-keyword">-</span><span>share.c</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> <</span><span class="z-string">stdint.h</span><span class="z-punctuation z-definition z-string">></span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">uint64_t</span><span class="z-entity z-name"> c_fib</span><span>(</span><span class="z-storage z-type">uint64_t</span><span class="z-variable"> n</span><span>)</span><span> {</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>n </span><span class="z-keyword"><=</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> return</span><span> n</span><span>;</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> c_fib</span><span>(</span><span>n </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span class="z-entity z-name"> c_fib</span><span>(</span><span>n </span><span class="z-keyword">-</span><span class="z-constant"> 2</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span>}</span></span></code></pre>
<p>接下来，让我们使用 <code>ctypes</code> 来调用它。主要的部分都很简单，需要注意的是，<code>uint64_t</code> 对应的是 <code>c_ulonglong</code> ，我们需要指定参数类型和结果类型。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">%</span><span class="z-keyword">%</span><span class="z-variable">file</span><span> fib</span><span class="z-keyword">-</span><span>ctypes</span><span>.</span><span>py</span></span>
<span class="giallo-l"><span class="z-keyword">from</span><span> ctypes</span><span class="z-keyword"> import</span><span class="z-constant"> CDLL</span><span>,</span><span> c_ulonglong</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> ctypes_fib</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>)</span><span>:</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Use ctypes to load the library</span></span>
<span class="giallo-l"><span> lib</span><span class="z-keyword"> =</span><span> CDLL</span><span>(</span><span class="z-punctuation z-definition z-string">'</span><span class="z-string">./ctypes_fib.so</span><span class="z-punctuation z-definition z-string">'</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> We need to give the argument and return types explicitly</span></span>
<span class="giallo-l"><span> lib</span><span>.</span><span>c_fib</span><span>.</span><span>argtypes</span><span class="z-keyword"> =</span><span> [</span><span>c_ulonglong</span><span>]</span></span>
<span class="giallo-l"><span> lib</span><span>.</span><span>c_fib</span><span>.</span><span>restype</span><span class="z-keyword"> =</span><span> c_ulonglong</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> lib</span><span>.</span><span>c_fib</span><span>(</span><span>n</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-support">print</span><span>(</span><span>ctypes_fib</span><span>(</span><span class="z-constant">47</span><span>)</span><span>)</span></span></code></pre>
<p>接着，我们需要编译共享库，并像运行其他 Python 程序那样执行。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> gcc</span><span class="z-constant"> -</span><span class="z-constant">O3</span><span class="z-constant"> -</span><span class="z-constant">fPIC</span><span class="z-constant"> -</span><span class="z-constant">shared</span><span class="z-constant"> -</span><span class="z-constant">std=c99</span><span class="z-string"> fib-share.c</span><span class="z-constant"> -</span><span class="z-constant">o</span><span class="z-string"> ctypes_fib.so</span></span>
<span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> python</span><span class="z-string"> fib-ctypes.py</span></span></code></pre>
<p><strong>CAPI</strong></p>
<p>相比其他几种方法，CAPI 会显得复杂一些，所以，我大概会推荐你去阅读 <a rel="nofollow noreferrer external" href="https://llllllllll.github.io/c-extension-tutorial/">How to Write and Debug C Extension Modules</a> 。</p>
<pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> <</span><span class="z-string">Python.h</span><span class="z-punctuation z-definition z-string">></span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage">static</span><span class="z-storage z-type"> unsigned</span><span class="z-storage z-type"> long</span></span>
<span class="giallo-l"><span class="z-entity z-name">cfib</span><span>(</span><span class="z-storage z-type">unsigned</span><span class="z-storage z-type"> long</span><span class="z-variable"> n</span><span>)</span></span>
<span class="giallo-l"><span>{</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>n </span><span class="z-keyword"><=</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> return</span><span> n</span><span>;</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> cfib</span><span>(</span><span>n </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span class="z-entity z-name"> cfib</span><span>(</span><span>n </span><span class="z-keyword">-</span><span class="z-constant"> 2</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name">PyDoc_STRVAR</span><span>(</span><span>fib_doc</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">compute the nth Fibonacci number</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage">static</span><span> PyObject</span><span class="z-keyword">*</span></span>
<span class="giallo-l"><span class="z-entity z-name">pyfib</span><span>(</span><span>PyObject</span><span class="z-keyword">*</span><span class="z-variable"> self</span><span>,</span><span> PyObject</span><span class="z-keyword">*</span><span class="z-variable"> n</span><span>)</span></span>
<span class="giallo-l"><span>{</span></span>
<span class="giallo-l"><span class="z-storage z-type"> unsigned</span><span class="z-storage z-type"> long</span><span> as_unsigned_long </span><span class="z-keyword">=</span><span class="z-entity z-name"> PyLong_AsUnsignedLong</span><span>(</span><span>n</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span> PyObject</span><span class="z-keyword">*</span><span> result </span><span class="z-keyword">=</span><span class="z-entity z-name"> PyLong_FromUnsignedLong</span><span>(</span><span class="z-entity z-name">cfib</span><span>(</span><span>as_unsigned_long</span><span>)</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> result</span><span>;</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>PyMethodDef methods</span><span class="z-storage">[]</span><span class="z-keyword"> =</span><span> {</span></span>
<span class="giallo-l"><span> {</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">fib</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span> (</span><span>PyCFunction</span><span>)</span><span> pyfib</span><span>,</span><span> METH_O</span><span>,</span><span> fib_doc</span><span>}</span><span>,</span></span>
<span class="giallo-l"><span> {</span><span class="z-constant">NULL</span><span>}</span><span>,</span></span>
<span class="giallo-l"><span>}</span><span>;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name">PyDoc_STRVAR</span><span>(</span><span>fib_module_doc</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">provides a Fibonacci function</span><span class="z-punctuation z-definition z-string">"</span><span>)</span><span>;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>PyModuleDef fib_module </span><span class="z-keyword">=</span><span> {</span></span>
<span class="giallo-l"><span> PyModuleDef_HEAD_INIT</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">fib</span><span class="z-punctuation z-definition z-string">"</span><span>,</span></span>
<span class="giallo-l"><span> fib_module_doc</span><span>,</span></span>
<span class="giallo-l"><span class="z-keyword"> -</span><span class="z-constant">1</span><span>,</span></span>
<span class="giallo-l"><span> methods</span><span>,</span></span>
<span class="giallo-l"><span class="z-constant"> NULL</span><span>,</span></span>
<span class="giallo-l"><span class="z-constant"> NULL</span><span>,</span></span>
<span class="giallo-l"><span class="z-constant"> NULL</span><span>,</span></span>
<span class="giallo-l"><span class="z-constant"> NULL</span></span>
<span class="giallo-l"><span>}</span><span>;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>PyMODINIT_FUNC</span></span>
<span class="giallo-l"><span class="z-entity z-name">PyInit_fib</span><span>(</span><span class="z-storage z-type">void</span><span>)</span></span>
<span class="giallo-l"><span>{</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> PyModule_Create</span><span>(</span><span class="z-keyword">&</span><span>fib_module</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span>}</span></span></code></pre>
<p>所有的函数返回类型都是 PyObject 的指针，参数类型是是 PyObject 的两个指针，前者对应 Python 类里方法的 self，后者对应串里的参数。</p>
<p>完成我们需要的函数之后，需要显示地声明模块暴露在外的方法，接受参数的类型以及文档。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> .</span><span>fib</span><span class="z-keyword"> import</span><span> fib</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-support z-variable">__all__</span><span class="z-keyword"> =</span><span> [</span><span class="z-punctuation z-definition z-string">'</span><span class="z-string">fib</span><span class="z-punctuation z-definition z-string">'</span><span>]</span></span></code></pre>
<p>构建 CPython 扩展模块的最常见方法是使用 setuptools 和 setup.py 文件。我们从一个普通的 setuptools setup.py 文件开始：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> setuptools</span><span class="z-keyword"> import</span><span> setup</span><span>,</span><span> find_packages</span><span>,</span><span> Extension</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>setup</span><span>(</span></span>
<span class="giallo-l"><span class="z-variable"> name</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">'</span><span class="z-string">fibcapi</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> version</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">'</span><span class="z-string">0.1.0</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> packages</span><span class="z-keyword">=</span><span>find_packages</span><span>(</span><span>)</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> classifiers</span><span class="z-keyword">=</span><span>[</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> '</span><span class="z-string">Development Status :: 3 - Alpha</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> '</span><span class="z-string">License :: OSI Approved :: GNU General Public License v2 (GPLv2)</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> '</span><span class="z-string">Natural Language :: English</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> '</span><span class="z-string">Programming Language :: Python :: 3 :: Only</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> '</span><span class="z-string">Programming Language :: Python :: Implementation :: CPython</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span> ]</span><span>,</span></span>
<span class="giallo-l"><span class="z-variable"> ext_modules</span><span class="z-keyword">=</span><span>[</span></span>
<span class="giallo-l"><span> Extension</span><span>(</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string"> '</span><span class="z-string">fib.fib</span><span class="z-punctuation z-definition z-string">'</span><span>,</span></span>
<span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-string">'</span><span class="z-string">fib/fib.c</span><span class="z-punctuation z-definition z-string">'</span><span>]</span><span>,</span></span>
<span class="giallo-l"><span> )</span><span>,</span></span>
<span class="giallo-l"><span> ]</span><span>,</span></span>
<span class="giallo-l"><span>)</span></span></code></pre>
<p>从根目录运行以下命令：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">python</span><span class="z-string"> setup.py</span><span class="z-string"> build_ext</span><span class="z-constant"> -</span><span class="z-constant">-inplace</span></span></code></pre>
<p>最后，像写一个普通的Python程序一样调用它。</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> fib</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-support">print</span><span>(</span><span>fib</span><span>.</span><span>fib</span><span>(</span><span class="z-constant">47</span><span>)</span><span>)</span></span></code></pre>
<p><strong>Cython</strong></p>
<p>如果使用 Cython, 代码可以更改为：</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>cdef</span><span class="z-variable"> long</span><span> fib</span><span>(</span><span class="z-variable">long</span><span> n</span><span>)</span><span>:</span></span>
<span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> <=</span><span class="z-constant"> 1</span><span>:</span><span class="z-keyword"> return</span><span> n</span></span>
<span class="giallo-l"><span class="z-keyword"> return</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> +</span><span> fib</span><span>(</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-support">print</span><span>(</span><span>fib</span><span>(</span><span class="z-constant">47</span><span>)</span><span>)</span></span></code></pre>
<p>需要使用下面的命令来编译：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">cython</span><span class="z-constant"> -</span><span class="z-constant">3</span><span class="z-constant"> -</span><span class="z-constant">-embed</span><span class="z-constant"> -</span><span class="z-constant">o</span><span class="z-string"> fib.pyx.c</span><span class="z-string"> fib.pyx</span><span> &&</span><span class="z-entity z-name"> gcc</span><span class="z-constant"> -</span><span class="z-constant">O3</span><span> $(</span><span class="z-entity z-name">python3-config</span><span class="z-constant"> -</span><span class="z-constant">-embed</span><span class="z-constant"> -</span><span class="z-constant">-cflags</span><span>)</span><span class="z-constant"> -</span><span class="z-constant">o</span><span class="z-string"> fib</span><span class="z-string"> fib.pyx.c</span><span> $(</span><span class="z-entity z-name">python3-config</span><span class="z-constant"> -</span><span class="z-constant">-embed</span><span class="z-constant"> -</span><span class="z-constant">-ldflags</span><span>)</span></span></code></pre>
<p><strong>SWIG</strong></p>
<p>首先，让我们复用之前 ctypes 一节中的 <code>fib-share.h</code> 和 <code>fib-share.c</code> 。</p>
<p>接着，定义对应的 SWIG 接口文件，为了使用 <code>uint64_t</code> ，我们不得不引入 <code>stdint.i</code> 。</p>
<pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span class="z-keyword">%</span><span class="z-keyword">%</span><span>file fib</span><span class="z-keyword">-</span><span>swig.i</span></span>
<span class="giallo-l"><span class="z-keyword">%</span><span>include </span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">stdint.i</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">%</span><span>module fibswig</span></span>
<span class="giallo-l"><span class="z-keyword">%</span><span>{</span></span>
<span class="giallo-l"><span class="z-storage">extern</span><span class="z-storage z-type"> uint64_t</span><span class="z-entity z-name"> c_fib</span><span>(</span><span class="z-storage z-type">uint64_t</span><span> n</span><span>)</span><span>;</span></span>
<span class="giallo-l"><span class="z-keyword">%</span><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage">extern</span><span class="z-storage z-type"> uint64_t</span><span class="z-entity z-name"> c_fib</span><span>(</span><span class="z-storage z-type">uint64_t</span><span class="z-variable"> n</span><span>)</span><span>;</span></span></code></pre>
<p>然后，我们需要编写一点 python 代码来调用 swig 共享库</p>
<pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> fibswig</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-support">print</span><span>(</span><span>fibswig</span><span>.</span><span>c_fib</span><span>(</span><span class="z-constant">47</span><span>)</span><span>)</span></span></code></pre>
<p>接着，我们需要编译共享库，并像运行其他 Python 程序那样执行。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> swig</span><span class="z-constant"> -</span><span class="z-constant">python</span><span class="z-string"> fib-swig.i</span></span>
<span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> gcc</span><span class="z-constant"> -</span><span class="z-constant">fPIC</span><span class="z-constant"> -</span><span class="z-constant">c</span><span class="z-string"> fib-share.c</span><span class="z-string"> fib-swig_wrap.c</span><span class="z-constant"> -</span><span class="z-constant">I</span><span class="z-string"> /usr/include/python3.10</span></span>
<span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> ld</span><span class="z-constant"> -</span><span class="z-constant">fPIC</span><span class="z-constant"> -</span><span class="z-constant">shared</span><span class="z-string"> fib-share.o</span><span class="z-string"> fib-swig_wrap.o</span><span class="z-constant"> -</span><span class="z-constant">o</span><span class="z-string"> _fibswig.so</span></span>
<span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> python</span><span class="z-string"> fib-swig.py</span></span></code></pre>
<p><strong>性能汇总</strong></p>
<table><thead><tr><th>Lang</th><th>Time, s</th></tr></thead><tbody>
<tr><td>Python3</td><td>530.974</td></tr>
<tr><td>Python3 (PyPy)</td><td>39.398</td></tr>
<tr><td>Python - Cache</td><td>0.013</td></tr>
<tr><td>C</td><td>3.336</td></tr>
<tr><td>ctypes</td><td>3.245</td></tr>
<tr><td>CAPI</td><td>3.300</td></tr>
<tr><td>Cython</td><td>4.487</td></tr>
<tr><td>SWIG</td><td>13.368</td></tr>
</tbody></table>
<h2 id="zhi-xie">致谢<a class="zola-anchor" href="#zhi-xie" aria-label="Anchor link for: zhi-xie" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="nofollow noreferrer external" href="https://leetcode.cn/problems/fibonacci-number/">509. 斐波那契数 - 力扣</a></li>
<li><a rel="nofollow noreferrer external" href="https://docs.python.org/3/extending/extending.html">Extending Python with C or C++</a></li>
<li><a rel="nofollow noreferrer external" href="https://docs.python.org/3/library/ctypes.html"><code>ctypes</code> — A foreign function library for Python</a></li>
<li><a rel="nofollow noreferrer external" href="https://realpython.com/build-python-c-extension-module/">Building a Python C Extension Module</a></li>
<li><a rel="nofollow noreferrer external" href="https://towardsdatascience.com/write-your-own-c-extension-to-speed-up-python-x100-626bb9d166e7">Write Your Own C-extension to Speed Up Python by 100x</a></li>
<li><a rel="nofollow noreferrer external" href="https://medium.com/delta-force/extending-python-with-c-f4e9656fbf5d">Extending Python with C</a></li>
<li><a rel="nofollow noreferrer external" href="https://web.mit.edu/people/amliu/vrut/python/ext/intro.html">Extending Python with C or C++ code</a></li>
<li><a rel="nofollow noreferrer external" href="https://www.zhihu.com/question/23003213">如何实现 C/C++ 与 Python 的通信？</a></li>
<li><a rel="nofollow noreferrer external" href="https://zhuanlan.zhihu.com/p/363434563">Python 和 C/C++ 拓展程序的性能优化</a></li>
<li><a rel="nofollow noreferrer external" href="https://blog.brickgao.com/2015/08/14/extending-Python-with-C-and-C-Plus-Plus/">用 C/C++ 拓展 Python</a></li>
</ul>
谈谈过去的一年
2022-07-05T00:00:00+00:00
2022-07-05T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/talk-about-the-past-year/
<p>这里是 PsiACE，本来应该继续写迭代记录之「十日谈」的，但距离上一期已经又过去月余，就不太提得起兴趣。</p>
<p>今天就做个特别篇好啦，毕竟 22 年已经过半，在职业道路上也慢慢前进了一年，算是一个比较有意思的时间节点。</p>
<h2 id="zhi-de-kai-xin-de-xiao-li-cheng-bei">值得开心的小里程碑<a class="zola-anchor" href="#zhi-de-kai-xin-de-xiao-li-cheng-bei" aria-label="Anchor link for: zhi-de-kai-xin-de-xiao-li-cheng-bei" style="visibility: hidden;"></a>
</h2>
<p><strong>个人向</strong></p>
<ul>
<li>减少碳水 + 增加散步 = 减重计划，颇有成效，瘦掉 7 、8 斤，感觉回到标准身材指日可待。</li>
<li>逐步开始有效的日程/时间管理，感觉比较关键的步骤是记录而非追踪。</li>
</ul>
<p><strong>开源向</strong></p>
<ul>
<li><a rel="nofollow noreferrer external" href="https://github.com/psiace/">@PsiACE</a> 累计 233 fo，<a rel="nofollow noreferrer external" href="https://twitter.com/repsiace">推上</a> 也有 300+ 。</li>
<li>在 <a rel="nofollow noreferrer external" href="https://github.com/datafuselabs/databend/">datafuselabs/databend</a> 上的提交数量突破 400 。</li>
<li><a rel="nofollow noreferrer external" href="https://github.com/dataslime/ritelinked">dataslime/ritelinked</a> 达成 10w 下载量，目前也有一些其他朋友在用。</li>
<li><a rel="nofollow noreferrer external" href="https://github.com/PsiACE/databend-internals">PsiACE/databend-internals</a> 最近好像被翻了牌子，目前有 160 star 。</li>
<li>开始在 <a rel="nofollow noreferrer external" href="https://github.com/casbin">@casbin</a> 的 GSoC 活动担任导师，也推动 Databend 参与 <a rel="nofollow noreferrer external" href="https://summer-ospp.ac.cn/">OSPP</a> 。</li>
</ul>
<h2 id="qing-nian-ren-de-xiao-xiao-fan-nao">青年人的小小烦恼<a class="zola-anchor" href="#qing-nian-ren-de-xiao-xiao-fan-nao" aria-label="Anchor link for: qing-nian-ren-de-xiao-xiao-fan-nao" style="visibility: hidden;"></a>
</h2>
<p><strong>生活向</strong></p>
<ul>
<li>可能关家里太久，整个人不太活跃，很多有趣的想法都搁置了下来。</li>
<li>好想女朋友，好想女朋友，好想女朋友。（疫情什么的，实在太讨厌了）</li>
<li>睡眠质量还蛮好，但是总觉得睡不太够，失眠也比较严重。</li>
</ul>
<p><strong>职业向</strong></p>
<ul>
<li>有几个月状态比较低落，虽然期间也搞出了 databend-perf 、databend-internals ，但确实不那么满意。</li>
<li><a rel="nofollow noreferrer external" href="https://perf.databend.rs/">databend-perf</a> 上线几个月，跑出不少 bug ，最近又在罢工。</li>
<li>前段时间 <a rel="nofollow noreferrer external" href="https://github.com/BohuTANG/">@BohuTANG</a> 问到入职一年来的成长，并提及 Owner 意识。感觉自己应该多向 <a rel="nofollow noreferrer external" href="https://github.com/Xuanwo">@Xuanwo</a> 、<a rel="nofollow noreferrer external" href="https://github.com/flaneur2020">@flaneur2020</a> 学习。</li>
</ul>
<h2 id="hou-xu-de-yi-xie-ji-hua">后续的一些计划<a class="zola-anchor" href="#hou-xu-de-yi-xie-ji-hua" aria-label="Anchor link for: hou-xu-de-yi-xie-ji-hua" style="visibility: hidden;"></a>
</h2>
<p><strong>学习向</strong></p>
<ul>
<li>把英语和数学往起捡一下。</li>
</ul>
<p><strong>工作向</strong></p>
<ul>
<li>试图对 databend-query 进行一轮 <a rel="nofollow noreferrer external" href="https://github.com/datafuselabs/databend/issues/6180">拆分</a> / <a rel="nofollow noreferrer external" href="https://github.com/datafuselabs/databend/issues/5001">测试重构</a> 。</li>
<li>继续打磨 <a rel="nofollow noreferrer external" href="https://github.com/PsiACE/databend-internals">PsiACE/databend-internals</a> ，及时增补新内容，争取正式并入 datafuselabs 进行维护。</li>
<li>持续探索开发者运营方面的一些好的形式和策略。</li>
<li>提高自己的技术水平和投入，争取能够落地一些 looks great 的想法。</li>
</ul>
<hr />
<p>暂时先这样，或许，下个迭代见！</p>
逃离编译时的内存溢出
2022-02-23T00:00:00+00:00
2022-02-23T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/escape-oom-at-build-time/
<p>今天写周报的时候提到了这个话题，顺便就记录一下如何逃离 Rust 编译时的内存溢出。</p>
<p>内存溢出，也就是 Out of Memory（OOM），从字面就能看出来，是要用到的内存大于系统能提供的最大内存而引起的故障。</p>
<p>Databend 中的 <a rel="nofollow noreferrer external" href="https://github.com/datafuselabs/databend/tree/main/common/functions">common/functions</a> 模块为用户提供常用 SQL 函数支持，体量本身就很大，并且在新一轮的改造中引入了很多需要 codegen 的环节。于是，我们又遇到了老朋友（CI 又挂了）：</p>
<blockquote>
<p>(signal: 9, SIGKILL: kill) warning: build failed, waiting for other jobs to finish... error: build failed.</p>
</blockquote>
<p>使用 <code>-Z time-passes</code> 这个 RUSTFLAGS 可以帮助观测一些指标，就很容易判断出来是 OOM 。而且之前的一些反馈和报错也能够佐证是发生在链接阶段。</p>
<p>那么，该怎么办呢？最简单的办法是「大就是好，多就是美」，加钱上更多内存，或者分配更大的 Swap 空间（没错，就像我之前有一个 <a rel="nofollow noreferrer external" href="https://psiace.me/btrfs-32gib-swapfile-on-fedora/">暴力的 32GiB Swapfile</a>）。这当然可以一劳永逸，但：前者无疑会消耗钱包，目前内存条还是一个很大的负担，而且对于笔记本之类，更换的余地也有限；后者虽然守住了钱包，但是白白占去那么大一块空间，而且说不得会影响一些性能。</p>
<p>让我们一起看一下，有没有什么过渡的选项可以缓解这一尴尬的局面，进行一些有限的平衡。</p>
<h2 id="geng-kuai-geng-gao-geng-qiang-de-mold">「更快、更高、更强」的 mold<a class="zola-anchor" href="#geng-kuai-geng-gao-geng-qiang-de-mold" aria-label="Anchor link for: geng-kuai-geng-gao-geng-qiang-de-mold" style="visibility: hidden;"></a>
</h2>
<p>是的，既然是链接器的问题，那么最简单的办法就是换一个。Rust 默认的 linker 选项设定的是 <code>cc</code>，这意味着会利用到 gnu 工具链中的 <code>ld</code>，尽管 gnu 在自由软件领域有着卓越的贡献，但以目前的经验而言，这并不是一个好的现代选择。它的一个有力的竞争者是 llvm 工具链中的 lld 。</p>
<p>而到了今天，我们还有另外一个更加优越的候选人 —— 「<a rel="nofollow noreferrer external" href="https://github.com/rui314/mold">mold</a>」，在实际使用中，表现出与 lld 相当、甚至超过的性能，并且使用更少的内存。</p>
<p>该如何与 Rust 工具链结合使用呢，有这么两种方法：</p>
<p><strong>mold -run</strong></p>
<p>采用这种模式，可以帮助我们快速体验 mold ，这得益于内置的拦截机制，可以将指向 ld ，ld.lld ，ld.gold 的命令转向 mold 自身。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> With Make.</span></span>
<span class="giallo-l"><span class="z-entity z-name">mold</span><span class="z-constant"> -</span><span class="z-constant">run</span><span class="z-string"> make</span><span class="z-keyword"> <</span><span class="z-string">make-options-if-an</span><span>y</span><span class="z-keyword">></span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Or with Cargo.</span></span>
<span class="giallo-l"><span class="z-entity z-name">mold</span><span class="z-constant"> -</span><span class="z-constant">run</span><span class="z-string"> cargo</span><span class="z-keyword"> <</span><span class="z-string">cargo-options-if-an</span><span>y</span><span class="z-keyword">></span></span></code></pre>
<p><strong>编辑 .cargo/config.toml</strong></p>
<p>添加下面的内容即可，如果是按 <code>sudo make install</code> 安装的，<code>path/to/mold</code> 大概率会指向 <code>/usr/local/bin/mold</code> 。</p>
<pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span>[</span><span class="z-entity z-name">target</span><span>.</span><span class="z-entity z-name">x86_64-unknown-linux-gnu</span><span>]</span></span>
<span class="giallo-l"><span class="z-variable z-other">linker</span><span> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">clang</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"><span class="z-variable z-other">rustflags</span><span> =</span><span> [</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">-C</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">link-arg=-fuse-ld=/path/to/mold</span><span class="z-punctuation z-definition z-string">"</span><span>]</span></span></code></pre><h2 id="chuan-xin-de-fu-hao-xiu-shi-fang-an">船新的符号修饰方案<a class="zola-anchor" href="#chuan-xin-de-fu-hao-xiu-shi-fang-an" aria-label="Anchor link for: chuan-xin-de-fu-hao-xiu-shi-fang-an" style="visibility: hidden;"></a>
</h2>
<p>符号修饰，或者说 symbol mangling ，是现代计算机程序设计语言的编译器用于解决由于程序实体的名字必须唯一而导致的问题的一种技术。</p>
<p>Rust 目前有一个自己设计符号修饰方案，<a rel="nofollow noreferrer external" href="https://github.com/rust-lang/rfcs/pull/2603">rust-lang/rfcs#2603</a>，通过启用这一方案，在有重复组件的情况下，会生成更小的符号。</p>
<p>要想启用这一特性，同样有两种方法：</p>
<p><strong>RUSTFLAGS</strong></p>
<p>在目前最新的 Rust nightly 中，可以使用 <code>-C symbol-manging-version=v0</code> 这个 RUSTFLAG ，相对旧一点的版本可能需要使用 <code>-Z symbol-manging-version=v0</code> 。</p>
<blockquote>
<p>RUSTFLAGS="-C symbol-manging-version=v0" cargo <cargo-options-if-any></p>
</blockquote>
<p><strong>编辑 .cargo/config.toml</strong></p>
<p>添加下面的内容即可，如果报错，请试试 <code>-Z</code>：</p>
<pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span>[</span><span class="z-entity z-name">target</span><span>.</span><span class="z-entity z-name">nightly-x86_64-unknown-linux-gnu</span><span>]</span></span>
<span class="giallo-l"><span class="z-variable z-other">rustflags</span><span> =</span><span> [</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">-C</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">symbol-mangling-version=v0</span><span class="z-punctuation z-definition z-string">"</span><span>]</span></span></code></pre><h2 id="huan-neng-zuo-shen-me">还能做什么？<a class="zola-anchor" href="#huan-neng-zuo-shen-me" aria-label="Anchor link for: huan-neng-zuo-shen-me" style="visibility: hidden;"></a>
</h2>
<p>拆分成更小的单元，让编译每个部分的时候不会太吃力；或者去掉一些笨重的依赖，让它不那么费劲；或者对编译选项进行更多调整，进行针对性优化。</p>
<p>好吧，今天就到这里咯，祝大家都能逃离 OOM ，换上更强悍的机器。</p>
<hr />
<p>笑死，清理了半天依赖，还剩下不到 900 个。</p>
论文十问
2022-02-19T00:00:00+00:00
2022-02-19T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/ten-questions-for-reading-a-paper/
<p>最近有试着在读论文，由于自身积累问题，往往试图跳过其中艰深的部分，不能很好汲取其中的精华。</p>
<p>最近看到沈向洋老师的 “论文十问”，觉得很有帮助，现摘抄如下：</p>
<h2 id="lun-wen-shi-wen">论文十问<a class="zola-anchor" href="#lun-wen-shi-wen" aria-label="Anchor link for: lun-wen-shi-wen" style="visibility: hidden;"></a>
</h2>
<ul>
<li><input disabled="" type="checkbox"/>
Q1 论文试图解决什么问题？</li>
<li><input disabled="" type="checkbox"/>
Q2 这是否是一个新的问题？</li>
<li><input disabled="" type="checkbox"/>
Q3 这篇文章要验证一个什么科学假设？</li>
<li><input disabled="" type="checkbox"/>
Q4 有哪些相关研究？如何归类？谁是这一课题在领域内值得关注的研究员？</li>
<li><input disabled="" type="checkbox"/>
Q5 论文中提到的解决方案之关键是什么？</li>
<li><input disabled="" type="checkbox"/>
Q6 论文中的实验是如何设计的？</li>
<li><input disabled="" type="checkbox"/>
Q7 用于定量评估的数据集是什么？代码有没有开源？</li>
<li><input disabled="" type="checkbox"/>
Q8 论文中的实验及结果有没有很好地支持需要验证的科学假设？</li>
<li><input disabled="" type="checkbox"/>
Q9 这篇论文到底有什么贡献？</li>
<li><input disabled="" type="checkbox"/>
Q10 下一步呢？有什么工作可以继续深入？</li>
</ul>
<h2 id="yi-dian-e-wai-shuo-ming">一点额外说明<a class="zola-anchor" href="#yi-dian-e-wai-shuo-ming" aria-label="Anchor link for: yi-dian-e-wai-shuo-ming" style="visibility: hidden;"></a>
</h2>
<ul>
<li>
<p>需要正确区分问题之间的边界，既要讲出关键，又不能车轱辘话来回滚。</p>
</li>
<li>
<p>尽量使用原文中的表达，并帮助没有前置知识的读者理解主题。</p>
</li>
<li>
<p>十答应当能够表达清楚论文的主要工作和贡献。</p>
</li>
</ul>
在 Fedora 上为 Btrfs 新建 32GiB Swapfile
2022-01-23T00:00:00+00:00
2022-01-23T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/btrfs-32gib-swapfile-on-fedora/
<p>受到 <a rel="nofollow noreferrer external" href="https://github.com/datafuselabs/databend/pull/3946">Databend - set swap to 10G</a> 的感召，检查了一下自己本子的 Swap ，只有大概 8G 的 zram 。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span>[</span><span>psiace@fedora </span><span class="z-keyword">~</span><span>]</span><span>$ swapon -s</span></span>
<span class="giallo-l"><span class="z-entity z-name">Filename</span><span class="z-string"> Type</span><span class="z-string"> Size</span><span class="z-string"> Used</span><span class="z-string"> Priority</span></span>
<span class="giallo-l"><span class="z-entity z-name">/dev/zram0</span><span class="z-string"> partition</span><span class="z-constant"> 8388604</span><span class="z-constant"> 0</span><span class="z-constant"> 100</span></span></code></pre>
<p>完蛋，不能顺利跑完 grcov 限定版 unit-test 的原因大概就在这里了（之前有讨论过是 OOM）。本着「大就是好，多就是美」的原则，决定给它来个超级加倍，再塞个 32 GiB 的 Swapfile 上去。</p>
<h2 id="btrfs-xian-ding-zhi-chu-shi-hua-swapfile">Btrfs 限定之初始化 Swapfile<a class="zola-anchor" href="#btrfs-xian-ding-zhi-chu-shi-hua-swapfile" aria-label="Anchor link for: btrfs-xian-ding-zhi-chu-shi-hua-swapfile" style="visibility: hidden;"></a>
</h2>
<p>自 5.0 内核之后，Btrfs 才支持创建 Swapfile ，而且有一些特别的要求：</p>
<ul>
<li>Swapfile 不能放在 snapshotted subvolume （快照子卷）上。</li>
<li>不支持跨多设备文件系统上的 Swapfile 。</li>
</ul>
<p>所以正确的做法是：新建一个 non-snapshotted subvolume ，然后在该子卷之下创建禁用压缩的 Swapfile 。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Create a non-snapshotted subvolume.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora /</span><span>]</span><span>$ sudo btrfs subvolume create swap</span></span>
<span class="giallo-l"><span class="z-entity z-name">Create</span><span class="z-string"> subvolume</span><span class="z-punctuation z-definition z-string"> '</span><span class="z-string">./swap</span><span class="z-punctuation z-definition z-string">'</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Enter the subvolume.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora /</span><span>]</span><span>$ cd swap</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Create a zero-length swapfile.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora swap</span><span>]</span><span>$ sudo truncate -s 0 ./swapfile</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Set the swapfile attribute to avoid copy-on-write.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora swap</span><span>]</span><span>$ sudo chattr +C ./swapfile</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Disable compression.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora swap</span><span>]</span><span>$ sudo btrfs property set ./swapfile compression none</span></span></code></pre>
<p>注意，这些需要在系统根目录下完成，以避免权限问题和设置问题。</p>
<h2 id="she-ding-swapfile-zuo-wei-swap-cheng-fen-zhi-yi">设定 Swapfile 作为 Swap 成分之一<a class="zola-anchor" href="#she-ding-swapfile-zuo-wei-swap-cheng-fen-zhi-yi" aria-label="Anchor link for: she-ding-swapfile-zuo-wei-swap-cheng-fen-zhi-yi" style="visibility: hidden;"></a>
</h2>
<p>Swapfile 是创建特定交换分区的一种替代方案，好处是方便创建和删除、也便于动态变更大小。</p>
<p>这种方案比较适合 SSD 空间充裕的情况。刚好可以组成一个 memory -> zram -> swapfile 的多级交换。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Fill the swapfile to a suitable size, usually half of memory or close to memory size.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This is only for fun, so I chose a huge 32GiB, which is admittedly wasteful.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora swap</span><span>]</span><span>$ sudo dd</span><span class="z-variable z-other"> if</span><span class="z-keyword">=</span><span class="z-string">/</span><span class="z-string">d</span><span class="z-string">e</span><span class="z-string">v</span><span class="z-string">/</span><span class="z-string">z</span><span class="z-string">e</span><span class="z-string">r</span><span class="z-string">o</span><span class="z-variable z-other"> of</span><span class="z-keyword">=</span><span class="z-string">.</span><span class="z-string">/</span><span class="z-string">s</span><span class="z-string">w</span><span class="z-string">a</span><span class="z-string">p</span><span class="z-string">f</span><span class="z-string">i</span><span class="z-string">l</span><span class="z-string">e</span><span class="z-variable z-other"> bs</span><span class="z-keyword">=</span><span class="z-string">1</span><span class="z-string">M</span><span class="z-variable z-other"> count</span><span class="z-keyword">=</span><span class="z-string">3</span><span class="z-string">2</span><span class="z-string">7</span><span class="z-string">6</span><span class="z-string">8</span><span class="z-variable z-other"> status</span><span class="z-keyword">=</span><span class="z-string">p</span><span class="z-string">r</span><span class="z-string">o</span><span class="z-string">g</span><span class="z-string">r</span><span class="z-string">e</span><span class="z-string">s</span><span class="z-string">s</span></span>
<span class="giallo-l"><span class="z-entity z-name">33980153856</span><span class="z-string"> bytes</span><span> (34</span><span class="z-string"> GB,</span><span class="z-constant"> 32</span><span class="z-string"> GiB</span><span>) copied, 20 s, 1.7 GB/s</span></span>
<span class="giallo-l"><span class="z-entity z-name">32768+0</span><span class="z-string"> records</span><span class="z-string"> in</span></span>
<span class="giallo-l"><span class="z-entity z-name">32768+0</span><span class="z-string"> records</span><span class="z-string"> out</span></span>
<span class="giallo-l"><span class="z-entity z-name">34359738368</span><span class="z-string"> bytes</span><span> (34</span><span class="z-string"> GB,</span><span class="z-constant"> 32</span><span class="z-string"> GiB</span><span>) copied, 21.2624 s, 1.6 GB/s</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Set correct permissions.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora swap</span><span>]</span><span>$ sudo chmod 600 ./swapfile</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Format the swapfile as swap.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora swap</span><span>]</span><span>$ sudo mkswap ./swapfile</span></span>
<span class="giallo-l"><span class="z-entity z-name">Setting</span><span class="z-string"> up</span><span class="z-string"> swapspace</span><span class="z-string"> version</span><span class="z-string"> 1,</span><span class="z-string"> size</span><span class="z-string"> =</span><span class="z-constant"> 32</span><span class="z-string"> GiB</span><span> (34359734272</span><span class="z-string"> bytes</span><span>)</span></span>
<span class="giallo-l"><span class="z-entity z-name">no</span><span class="z-string"> label,</span><span class="z-string"> UUID=2e48f371-62a9-487a-9613-382b386b2836</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Enable the swapfile and set its priority.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Since zram has priority 100, set this to 50. After all, zram is much faster than a swapfile.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora swap</span><span>]</span><span>$ sudo swapon --priority 50 ./swapfile</span></span></code></pre><h2 id="jian-cha-swap-kong-jian-bing-she-zhi-zi-dong-gua-zai">检查 Swap 空间并设置自动挂载<a class="zola-anchor" href="#jian-cha-swap-kong-jian-bing-she-zhi-zi-dong-gua-zai" aria-label="Anchor link for: jian-cha-swap-kong-jian-bing-she-zhi-zi-dong-gua-zai" style="visibility: hidden;"></a>
</h2>
<p>那么，经过之前两步，已经得到了接近 40GiB 的 Swap 空间，接下来就是检查一下，并设置挂载。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Use free to check the overview.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora </span><span class="z-keyword">~</span><span>]</span><span>$ free -m</span></span>
<span class="giallo-l"><span class="z-entity z-name"> total</span><span class="z-string"> used</span><span class="z-string"> free</span><span class="z-string"> shared</span><span class="z-string"> buff/cache</span><span class="z-string"> available</span></span>
<span class="giallo-l"><span class="z-entity z-name">Mem:</span><span class="z-constant"> 15453</span><span class="z-constant"> 5206</span><span class="z-constant"> 290</span><span class="z-constant"> 109</span><span class="z-constant"> 9956</span><span class="z-constant"> 9808</span></span>
<span class="giallo-l"><span class="z-entity z-name">Swap:</span><span class="z-constant"> 40959</span><span class="z-constant"> 2</span><span class="z-constant"> 40957</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Use swapon to check details.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora </span><span class="z-keyword">~</span><span>]</span><span>$ swapon -s</span></span>
<span class="giallo-l"><span class="z-entity z-name">Filename</span><span class="z-string"> Type</span><span class="z-string"> Size</span><span class="z-string"> Used</span><span class="z-string"> Priority</span></span>
<span class="giallo-l"><span class="z-entity z-name">/dev/zram0</span><span class="z-string"> partition</span><span class="z-constant"> 8388604</span><span class="z-constant"> 2560</span><span class="z-constant"> 100</span></span>
<span class="giallo-l"><span class="z-entity z-name">/swap/swapfile</span><span class="z-string"> file</span><span class="z-constant"> 33554428</span><span class="z-constant"> 0</span><span class="z-constant"> 50</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Edit fstab and add an entry to mount it.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> The subvolume name must be included here. UUID is optional.</span></span>
<span class="giallo-l"><span>[</span><span>psiace@fedora </span><span class="z-keyword">~</span><span>]</span><span>$ sudo nano /etc/fstab</span></span>
<span class="giallo-l"><span class="z-entity z-name">/swap/swapfile</span><span class="z-string"> none</span><span class="z-string"> swap</span><span class="z-string"> defaults</span><span class="z-constant"> 0</span><span class="z-constant"> 0</span></span></code></pre><h2 id="can-kao-zi-liao">参考资料<a class="zola-anchor" href="#can-kao-zi-liao" aria-label="Anchor link for: can-kao-zi-liao" style="visibility: hidden;"></a>
</h2>
<p>笑死，一个多年 Fedora 用户看的文档大多都来自 Arch Wiki 。</p>
<ul>
<li>https://wiki.archlinux.org/title/Improving_performance#zram_or_zswap</li>
<li>https://wiki.archlinux.org/title/Btrfs#Swap_file</li>
<li>https://wiki.archlinux.org/title/Swap#Swap_file_creation</li>
<li>https://wiki.archlinux.org/title/Fstab</li>
</ul>
<hr />
<p>克制 Rust 编译大型项目时 OOM 还有一些小技巧，也许下次可以水一点内容。</p>
<p>我没有摸鱼！（手动狗头）</p>
2021 年度总结 - Life is not a struggle
2022-01-01T00:00:00+00:00
2022-01-01T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/2021-life-is-not-a-struggle/
<p>说是年度总结，却是在 2022 的第一天夜里才匆匆写几句，就是留个念头。</p>
<p>2021 年首要的关键字就是 <strong>「工作」</strong> 咯，从 7 月份入职，整整半年过去，应该算是顺利成为职场新人了。非常感谢 <a rel="nofollow noreferrer external" href="https://github.com/BohuTANG">@BohuTANG</a> 和 Datafuse Labs，让我有机会体验「全职开源 + 远程办公」的生活。成功凑了不少 commits 在 GitHub 上，还要继续努力才行。</p>
<p>回过头看看 2021 上半年，几乎就只有两次答辩的时候去了一段时间学校，感觉确实是离校园生活越来越远了。中间五月份因为扭伤比较严重，在床上躺了将近一个月，想起来还挺怨念的。不知道能不能有机会边工作边读读书（xs，总想着回炉重造是怎么回事）。</p>
<p>总之呢，2021 已经过去了。「Life is not a struggle」，希望自己能够与生活和解。新的一年，不要那么贪心，做好每一件事情，扎扎实实投入到学习和工作之中。</p>
<hr />
<p>另，昨天发了好多遍「早睡早起」，然而还是没做到 :(</p>
Arch Linux 初始服务器设置
2018-09-11T00:00:00+00:00
2018-09-11T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/init-server-setup-with-archlinux/
<p><strong>本文所涉步骤仅在阿里云上进行了验证，但应当同样适用于其它云服务供应商。</strong></p>
<h2 id="part-0-qian-yan">Part 0：前言<a class="zola-anchor" href="#part-0-qian-yan" aria-label="Anchor link for: part-0-qian-yan" style="visibility: hidden;"></a>
</h2>
<p>我刚刚完成从 Red Hat 系（Fedora, CentOS）<del>完全</del>迁移到 <a rel="nofollow noreferrer external" href="https://www.archlinux.org/">Arch Linux</a> 的过程，这并不算是一个十分稳妥的选择，因为 Red Hat 系向来以高可靠性著称，即便是被称作试验田的 Fedora 也很少会因为稀奇古怪的问题而崩溃。但是，Arch Linux 作为一个滚动更新的发行版，它可以满足我对新鲜事物的好奇，并且该发行版提供的 Arch Wiki 以及 AUR 确实是值得我喜爱。</p>
<p>在将桌面系统更换为 Manjaro Linux（一个基于 Arch Linux 的发行版，便于上手）之后，我开始准备将我在阿里云的 ECS 实例也切换到 Arch Linux 上。在这里有一个小小的争论，因为大部分人认为这不是一个稳妥的选择，频繁更新造成的不稳定，以及需要重启以确保它可以正常启用服务。但另一方面，使用 Arch Linux 的好处同样很明显，时刻最新有助于安全性的提升，丰富的软件和优秀的用户群在各个方面提供帮助（是的，而且我觉得他们足够活跃，这至少意味着你的问题可以得到更加及时的回应），最重要的，百科全书式的 Arch Wiki（在所有 GNU/Linux 系统里，只有两个在相关方面如此出色，另一个是 Gentoo）。我知道这并不足以说服那些追求稳定服务的运维人员，但至少我说服了我自己。值得一提的是 Arch Linux 的官网是运行在 Arch Linux 服务器上的。</p>
<p>好吧，让我们开始！</p>
<h2 id="part-1-shi-yong-vps2arch-chuang-jian-arch-linux-fu-wu-qi">Part 1：使用 vps2arch 创建 Arch Linux 服务器<a class="zola-anchor" href="#part-1-shi-yong-vps2arch-chuang-jian-arch-linux-fu-wu-qi" aria-label="Anchor link for: part-1-shi-yong-vps2arch-chuang-jian-arch-linux-fu-wu-qi" style="visibility: hidden;"></a>
</h2>
<p>说实在的，我更喜欢 Vultr，因为它提供的操作系统版本更新，而且有我一直喜爱的 Fedora。不过这都不重要了，因为它们都不直接支持 Arch Linux，我正在考虑要不要添加它的徽标到正在设计的网站上，这样一定会吸引不少人的目光。</p>
<p>创建自定义镜像是一件麻烦的工作，它需要花费一定的时间，而且并不是一项对新手友好的事情。好在，我们有 <a rel="nofollow noreferrer external" href="https://gitlab.com/drizzt/vps2arch/">vps2arch</a>，感谢 <a rel="nofollow noreferrer external" href="https://gitlab.com/drizzt">@drizzt</a> 以及其他贡献者所作出的努力。在一个初始创建为 CentOS 7.4 的 ECS 实例上，我们仅仅需要执行三条命令，接下来就可以完全按照提示进行了。</p>
<p><strong>注意，一切数据将会被清空，但将保留你的 root 密码并提供一个支持 SSH 的基础系统。</strong></p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">wget</span><span class="z-string"> http://tinyurl.com/vps2arch</span></span>
<span class="giallo-l"><span class="z-entity z-name">chmod</span><span class="z-string"> +x</span><span class="z-string"> vps2arch</span></span>
<span class="giallo-l"><span class="z-entity z-name">./vps2arch</span></span></code></pre>
<p>重启之后，你将进入到 Arch Linux 中，一切都准备好了。</p>
<h2 id="part-2-cai-qu-yi-xie-pei-zhi-bu-zou-zuo-wei-ji-ben-she-zhi-de-yi-bu-fen">Part 2：采取一些配置步骤作为基本设置的一部分<a class="zola-anchor" href="#part-2-cai-qu-yi-xie-pei-zhi-bu-zou-zuo-wei-ji-ben-she-zhi-de-yi-bu-fen" aria-label="Anchor link for: part-2-cai-qu-yi-xie-pei-zhi-bu-zou-zuo-wei-ji-ben-she-zhi-de-yi-bu-fen" style="visibility: hidden;"></a>
</h2>
<h3 id="yuan-cheng-ssh-lian-jie">远程 SSH 连接<a class="zola-anchor" href="#yuan-cheng-ssh-lian-jie" aria-label="Anchor link for: yuan-cheng-ssh-lian-jie" style="visibility: hidden;"></a>
</h3>
<p>你可以先在本地尝试一下 <code>ssh root@your.ecs.ip.address</code>，如果你此前没有使用过 SSH 连接，它可能是可用的。但如果用过，则会出现一大段警告，并无法连接。</p>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</span></span>
<span class="giallo-l"><span>@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @</span></span>
<span class="giallo-l"><span>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</span></span>
<span class="giallo-l"><span>IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!</span></span>
<span class="giallo-l"><span>Someone could be eavesdropping on you right now (man-in-the-middle attack)!</span></span>
<span class="giallo-l"><span>It is also possible that a host key has just been changed.</span></span></code></pre>
<p>这个时候，我们需要使用 <code>ssh-keygen -R your.ecs.ip.address</code> 来清除产生冲突的旧密钥。再重新进行连接。厌倦了每次输入密码？那么考虑在本地使用 <code>ssh-copy-id username@your.ecs.ip.address</code> 将公钥添加到服务器中。之后，你应当可以直接连接到 ECS 实例。</p>
<h3 id="chuang-jian-fei-root-yong-hu-bing-cai-yong-sudo-shou-yu-guan-li-quan-xian">创建非 ROOT 用户并采用 SUDO 授予管理权限<a class="zola-anchor" href="#chuang-jian-fei-root-yong-hu-bing-cai-yong-sudo-shou-yu-guan-li-quan-xian" aria-label="Anchor link for: chuang-jian-fei-root-yong-hu-bing-cai-yong-sudo-shou-yu-guan-li-quan-xian" style="visibility: hidden;"></a>
</h3>
<p>使用 SSH 连接到你的服务器。</p>
<p><code>useradd newusername</code> 将添加一个名为 newusername 的用户，而 <code>passwd newusername</code> 将为他设置密码。</p>
<p>接下来需要创建用户主目录并赋权，否则在你切换到新用户后仍然停留在根目录里（命令行提示会指出）。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">mkdir</span><span class="z-string"> /home/newusername</span></span>
<span class="giallo-l"><span class="z-entity z-name">chown</span><span class="z-string"> newusername:newusername</span><span class="z-string"> /home/newusername</span></span></code></pre>
<p>为了能够给新建用户授予管理权限，我们首先要安装 sudo 并编辑 <code>/etc/sudoers</code> 文件。<code>pacman -S sudo</code> 安装 sudo，<code>chmod u+w /etc/sudoers</code> 增加写权限；采用 <code>vi /etc/sudoers</code> 编辑，在 <code>root ALL=(ALL) ALL</code> 下面一行添加 <code>newusername ALL=(ALL) ALL</code>，保存退出；<code>chmod u-w /etc/sudoers</code> 撤销写权限。</p>
<p>采用 <code>su - newusername</code> 切换用户到 newusername。</p>
<h3 id="ji-ben-fang-huo-qiang">基本防火墙<a class="zola-anchor" href="#ji-ben-fang-huo-qiang" aria-label="Anchor link for: ji-ben-fang-huo-qiang" style="visibility: hidden;"></a>
</h3>
<p>iptables 已经被安装到了 Arch Linux 中，如果你不是很喜欢使用这个复杂的配置工具，我们可以选择使用 ufw 来进行接下来的步骤。（阿里云的安全组特性已经提供了类似防火墙的访问控制功能，但我认为服务器端也应该做出控制）</p>
<p>此时我们只需要确保防火墙允许 SSH 可以正常连接。</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> pacman</span><span class="z-constant"> -</span><span class="z-constant">S</span><span class="z-string"> ufw</span></span>
<span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> ufw</span><span class="z-string"> app</span><span class="z-string"> list</span></span>
<span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> ufw</span><span class="z-string"> allow</span><span class="z-string"> SSH</span></span>
<span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> ufw</span><span class="z-string"> enable</span></span></code></pre>
<p>此时防火墙已经开启，使用 <code>sudo ufw status</code> 可以查看当前状态。</p>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Status: active</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>To Action From</span></span>
<span class="giallo-l"><span>-- ------ ----</span></span>
<span class="giallo-l"><span>SSH ALLOW Anywhere</span></span>
<span class="giallo-l"><span>SSH (v6) ALLOW Anywhere (v6)</span></span></code></pre><h3 id="pu-tong-yong-hu-de-ssh-fang-wen">普通用户的 SSH 访问<a class="zola-anchor" href="#pu-tong-yong-hu-de-ssh-fang-wen" aria-label="Anchor link for: pu-tong-yong-hu-de-ssh-fang-wen" style="visibility: hidden;"></a>
</h3>
<p>你应当可以用类似 ROOT 用户的方法通过 SSH 登录到远程服务器，<code>ssh newusername@your.ecs.ip.address</code>，输入密码。</p>
<p>本地采用上面提到的 <code>ssh-copy-id</code> 命令可以帮助你启用密钥身份验证。</p>
<p>如果你在 root 用户下已经启用了 SSH 密钥验证，可以通过 rsync 将其复制到普通用户的目录下。（这里假设你仍是上面的普通用户）</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> pacman</span><span class="z-constant"> -</span><span class="z-constant">S</span><span class="z-string"> rsync</span></span>
<span class="giallo-l"><span class="z-entity z-name">mkdir</span><span class="z-string"> .ssh</span></span>
<span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> su</span><span class="z-string"> -</span><span class="z-string"> root</span></span>
<span class="giallo-l"><span class="z-entity z-name">rsync</span><span class="z-constant"> -</span><span class="z-constant">-archive</span><span class="z-constant"> -</span><span class="z-constant">-chown=newusername:newusername</span><span class="z-string"> ~/.ssh</span><span class="z-string"> /home/newusername</span></span></code></pre>
<p>最后一条语句经测试只能在 root 用户下使用，采用 sudo 指令不可行。</p>
<p>关闭连接，采用 <code>ssh newusername@your.ecs.ip.address</code>，这时应该可以正常使用密钥验证。</p>
<h2 id="part-3-jie-xia-lai">Part 3：接下来...<a class="zola-anchor" href="#part-3-jie-xia-lai" aria-label="Anchor link for: part-3-jie-xia-lai" style="visibility: hidden;"></a>
</h2>
<p>基本的服务器配置已经处理好了，你可以着手去做你想要做的事情，或许从 <a rel="nofollow noreferrer external" href="https://github.com/Kickball/awesome-selfhosted">Awesome Selfhosted</a> 中挑选一个自托管服务是一个不错的选择。</p>
在 Linux 上运行 MASM 汇编
2018-09-06T00:00:00+00:00
2018-09-06T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/masm-on-linux/
<p>在 Linux 环境下使用汇编，使用 NASM 或是 GNU AS 无疑会方便很多，但国内的课程大多采用 MASM 进行讲解和作业，为了适应课堂需要，我们需要配置学习环境。</p>
<p>首先，使用最喜欢的包管理工具安装 DOSBox，例如 <code>sudo dnf install dosbox</code>。该软件是一个使用 SDL 库的 DOS 模拟程序，可以再现一个 MS-DOS 兼容环境。</p>
<p>其次，你需要准备使用的 MASM 软件，通常情况下，教师会为你提供 MASM 5.0 上机学习环境（包括 MASM.EXE LINK.EXE LIB.EXE 以及 CREF.EXE），这是可以在 DOS 环境下运行的几个版本之一，请下载它。当然你也可以自行寻找其它合适版本的 MASM，并找出这些程序。</p>
<p>接下来，把你找到的程序（至少包括 MASM.EXE LINK.EXE LIB.EXE 以及 CREF.EXE）放入 <code>~/.dosbox/MASM</code> 之中（需要在 <code>.dosbox</code> 下新建），然后在 <code>~/.dosbox/dosbox-0.74.conf</code> 中的 <code>[autoexec]</code> 部分录入：</p>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[autoexec]</span></span>
<span class="giallo-l"><span># Lines in this section will be run at startup.</span></span>
<span class="giallo-l"><span># You can put your MOUNT lines here.</span></span>
<span class="giallo-l"><span>MOUNT c /home/yourusername/.dosbox/MASM</span></span>
<span class="giallo-l"><span>set PATH= %PATH%;c:\;</span></span>
<span class="giallo-l"><span>mount E /home/yourusername/asm</span></span>
<span class="giallo-l"><span>E:</span></span></code></pre>
<p>好了，我们的安装准备已经完成，接下来是测试时间。</p>
<p>在你上面选择存放 <code>.asm</code> 的文件中新建 <code>hello.asm</code>，将 hello world 例程录入：</p>
<pre class="giallo z-code"><code data-lang="asm"><span class="giallo-l"><span>assume </span><span class="z-constant">cs</span><span>:codes, </span><span class="z-constant">ds</span><span>:datas</span></span>
<span class="giallo-l"><span>datas segment</span></span>
<span class="giallo-l"><span class="z-keyword"> str</span><span class="z-storage z-type"> db</span><span> 'hello,world',</span><span class="z-constant">13</span><span>,</span><span class="z-constant">10</span><span>,'$'</span></span>
<span class="giallo-l"><span>datas ends</span></span>
<span class="giallo-l"><span>codes segment</span></span>
<span class="giallo-l"><span class="z-entity z-name"> start</span><span class="z-entity z-name">:</span></span>
<span class="giallo-l"><span class="z-keyword"> mov</span><span class="z-constant"> ax</span><span>, datas</span></span>
<span class="giallo-l"><span class="z-keyword"> mov</span><span class="z-constant"> ds</span><span>, </span><span class="z-constant">ax</span></span>
<span class="giallo-l"><span class="z-keyword"> lea</span><span class="z-constant"> dx</span><span>, </span><span class="z-keyword">str</span></span>
<span class="giallo-l"><span class="z-keyword"> mov</span><span class="z-constant"> ah</span><span>, </span><span class="z-constant">9</span></span>
<span class="giallo-l"><span class="z-keyword"> int</span><span class="z-constant"> 21h</span></span>
<span class="giallo-l"><span class="z-keyword"> mov</span><span class="z-constant"> ah</span><span>, </span><span class="z-constant">4ch</span></span>
<span class="giallo-l"><span class="z-keyword"> int</span><span class="z-constant"> 21h</span></span>
<span class="giallo-l"><span>codes ends</span></span>
<span class="giallo-l"><span> end start</span></span></code></pre>
<p>打开 DOSBox，在命令行依次执行 <code>masm hello.asm</code>、<code>link hello.obj</code> 以及 <code>hello.exe</code>。如果配置成功，程序会输出 <code>hello,world</code>，这意味着我们的 MASM 学习环境已经配置成功了。</p>
<hr />
<p>9 月 24 日补充：</p>
<p>关于 <code>~/.dosbox/dosbox-0.74.conf</code> 的设置：<code>MOUNT c path/to/your/folder</code> 是指定 C 盘的位置，所以完全可以用其他位置来代替。<code>set PATH= %PATH%;c:\;</code> 一句设定了环境变量。</p>
<p>关于 DEBUG 程序：直接放置到 C 盘目录之下即可，输入 <code>debug</code> 即可运行。</p>
<p>关于下载：可以在 <a rel="nofollow noreferrer external" href="http://www.phatcode.net">http://www.phatcode.net</a> 找到相关内容。下载后直接解压，然后找出你所需要的内容放置在 C 盘下即可。</p>
尝试使用 Jekyll 与 GitHub Pages
2018-07-14T00:00:00+00:00
2018-07-14T00:00:00+00:00
Unknown
https://psiace.me/zh/posts/try-jekyll-with-github/
<p><em>本文将帮助你快速入门，为了避免在介绍上花费过多时间，部分内容请感兴趣的同学自己查看官方网站和文档。</em></p>
<p><a rel="nofollow noreferrer external" href="https://jekyllrb.com">Jekyll</a> 是一个优秀的静态站点生成器，<a rel="nofollow noreferrer external" href="https://pages.github.com">GitHub Pages</a> 是 <strong>GitHub</strong> 提供的静态页面托管服务。使用这些，我们可以轻松地为项目/组织构建网站，也可以发布自己的博客和简历。</p>
<p>同时使用 Jekyll 和 GitHub Pages 的一个最大的好处是你可以只关注内容，这是由于有很多优秀的设计师和开发人员为 Jekyll 制作了大量的美观实用的主题，而 GitHub 为我们节约了购置服务器的经费。唯一的限制可能仅仅是我们需要一些第三方服务来提供诸如评论和在线表单这样的功能。</p>
<p>本文会介绍以下几个方面的内容：</p>
<ul>
<li>本地部署 Jekyll/GitHub Pages 环境</li>
<li>启用 GitHub Pages 的用户页面服务</li>
<li>使用优秀的 Jekyll Theme</li>
<li>Jekyll Theme 的组织结构</li>
<li>一些第三方服务和个性化配置</li>
<li>将你的页面发布 :)</li>
</ul>
<p>好吧，让我们现在就开始，玩的开心～</p>
<h2 id="ben-di-bu-shu-jekyll-github-pages-huan-jing">本地部署 Jekyll/GitHub Pages 环境<a class="zola-anchor" href="#ben-di-bu-shu-jekyll-github-pages-huan-jing" aria-label="Anchor link for: ben-di-bu-shu-jekyll-github-pages-huan-jing" style="visibility: hidden;"></a>
</h2>
<p>首先我们需要一台联网的计算机，当然，如果没有也不用担心，我会考虑在后面添加如何使用手机来完成这项工作。</p>
<p>首先，你需要安装 Ruby 语言环境，这里提供 Fedora 系统上的命令行安装方法：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> dnf</span><span class="z-string"> install</span><span class="z-string"> ruby</span><span class="z-string"> ruby-devel</span></span></code></pre>
<p>如果你使用的是 Ubuntu 系统，只需要把命令换成：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">sudo</span><span class="z-string"> apt-get</span><span class="z-string"> install</span><span class="z-string"> ruby</span><span class="z-string"> ruby-dev</span></span></code></pre>
<p>至于 <code>[Y/N]</code> 我们当然是选择 Y :)</p>
<p>如果你在使用 Windows 或是其它操作系统，请参考 <a rel="nofollow noreferrer external" href="https://www.ruby-lang.org">Ruby 官网</a>，你可以很轻易得到安装办法。</p>
<p>接下来，使用 GitHub Pages 推荐的依赖方式创建本地环境。可以先安装 Bundler，然后在项目中通过 <code>github-pages</code> 这个 gem 对齐 GitHub Pages 环境：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">gem</span><span class="z-string"> install</span><span class="z-string"> bundler</span></span>
<span class="giallo-l"><span class="z-entity z-name">mkdir</span><span class="z-string"> myblog</span></span>
<span class="giallo-l"><span class="z-support">cd</span><span class="z-string"> myblog</span></span>
<span class="giallo-l"><span class="z-entity z-name">bundle</span><span class="z-string"> init</span></span></code></pre>
<p>在 <code>Gemfile</code> 中添加：</p>
<pre class="giallo z-code"><code data-lang="ruby"><span class="giallo-l"><span>gem </span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">github-pages</span><span class="z-punctuation z-definition z-string">"</span><span>,</span><span class="z-constant"> group</span><span class="z-constant">:</span><span class="z-constant"> :</span><span class="z-constant">jekyll_plugins</span></span></code></pre>
<p>然后执行：</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">bundle</span><span class="z-string"> install</span></span>
<span class="giallo-l"><span class="z-entity z-name">bundle</span><span class="z-string"> exec</span><span class="z-string"> jekyll</span><span class="z-string"> new</span><span class="z-string"> .</span><span class="z-constant"> -</span><span class="z-constant">-force</span></span>
<span class="giallo-l"><span class="z-entity z-name">bundle</span><span class="z-string"> exec</span><span class="z-string"> jekyll</span><span class="z-string"> serve</span></span></code></pre>
<p>不直接使用 <code>gem install bundler jekyll</code> 的原因只是我们想要构建一个与 GitHub Pages 完全相同的环境。</p>
<p>在浏览器中输入它提供的地址（也许是 <code>http://localhost:4000</code> 或是 <code>http://127.0.0.1:4000/</code>），你就可以看到一个官方提供的模板。</p>
<p>如果你喜欢它，可以直接在这个上开始工作，打开文件夹，在 <code>_posts</code> 目录下以 <code>yyyy-mm-dd-title.md</code> 按示例新建文件，编辑内容，然后就可以在页面上看到更改了，稍后我会额外介绍这些内容。</p>
<h2 id="qi-yong-github-pages-de-yong-hu-ye-mian-fu-wu">启用 GitHub Pages 的用户页面服务<a class="zola-anchor" href="#qi-yong-github-pages-de-yong-hu-ye-mian-fu-wu" aria-label="Anchor link for: qi-yong-github-pages-de-yong-hu-ye-mian-fu-wu" style="visibility: hidden;"></a>
</h2>
<p>如果你还没有 <a rel="nofollow noreferrer external" href="https://github.com">GitHub</a> 的账号，我强烈推荐你注册一个，因为这是世界上最为活跃的<del>同性</del>交友社区之一 :) 只要访问主页，你就可以找到入口。</p>
<p>我强烈建议你参考 GitHub 的官方文档，它非常详细地介绍了所有你可能想要了解的内容。当然，你需要一点阅读英文文档的能力，至少要能够使用翻译。</p>
<p>好了，现在你已经有了 GitHub 的账号，通常情况下，我会建议你创建一个名为 <code>yourusername.github.io</code> 的存储库（请容许它使用 README 文档对存储库进行初始化，特别是当你打算试验而没有准备好内容），这样你就可以获得一个由 GitHub 友情提供的子域名，所有在主分支（<code>master</code>）的符合要求的内容都将被重构并发布，通常情况下，你可以在浏览器访问 <code>https://yourusername.github.io</code>，然后看到 <code>README.md</code> 被转化后的内容。</p>
<p>如果它没有正常显示或者你想在其它存储库启用 GitHub Pages，请打开存储库的 <code>Settings</code> 然后根据提示操作。如果你觉得页面光秃秃，可以通过 <code>Choose a theme</code> 来选择一个官方主题，但这不是必要的，因为我们接下来会介绍一些关于使用优秀的 Jekyll 主题和进一步定制的内容。</p>
<h2 id="shi-yong-you-xiu-de-jekyll-theme">使用优秀的 Jekyll Theme<a class="zola-anchor" href="#shi-yong-you-xiu-de-jekyll-theme" aria-label="Anchor link for: shi-yong-you-xiu-de-jekyll-theme" style="visibility: hidden;"></a>
</h2>
<p>造轮子是一件有意思的工作，但它往往需要花费大量的时间，而且一个好的想法可能需要经过大量的调试才能正常工作，如果你不满足于 Jekyll 的几个默认主题，那么我建议你试着使用一些优秀的 Jekyll 主题，它们往往实现了以下功能：</p>
<ul>
<li>响应式布局</li>
<li>良好的文件结构</li>
<li>标签云/文章分类</li>
<li>优化的 SEO 设置</li>
<li>第三方评论/统计插件支持</li>
</ul>
<p>从优秀的 Jekyll 主题开始可以让你更专注于文章本身，而不是看上去数目众多的 CSS 代码 :)</p>
<p>这里我特别推荐三个主题：</p>
<ul>
<li><strong><a rel="nofollow noreferrer external" href="https://github.com/Huxpro/huxblog-boilerplate">Huxblog-Boilerplate</a></strong>，by <a rel="nofollow noreferrer external" href="https://github.com/Huxpro/">@Huxpro</a>，Apache License v2.0</li>
<li><strong><a rel="nofollow noreferrer external" href="https://github.com/Simpleyyt/jekyll-theme-next">Jekyll NexT</a></strong>，by <a rel="nofollow noreferrer external" href="https://github.com/Simpleyyt/">@Simpleyyt</a>，Unknown</li>
<li><strong><a rel="nofollow noreferrer external" href="https://github.com/renyuanz/leonids">Leonids</a></strong>，by <a rel="nofollow noreferrer external" href="https://github.com/renyuanz/">@renyuanz</a>，MIT License</li>
</ul>
<p>点击主题名，你将跳转到它们的存储库，请选择你所喜欢的主题下载。</p>
<p>相信我，我们可以完全避开 Git 以及它的命令行工具，如果你不想跳过这些，那么你可能需要另外查看其它文章，我暂时没有介绍这些的计划。</p>
<p>如果你想查找更多主题，我强烈建议你查看 <a rel="nofollow noreferrer external" href="http://jekyllthemes.org">Jekyll Themes</a>，请从中挑选你喜欢的那个。</p>
<h2 id="jekyll-theme-de-zu-zhi-jie-gou">Jekyll Theme 的组织结构<a class="zola-anchor" href="#jekyll-theme-de-zu-zhi-jie-gou" aria-label="Anchor link for: jekyll-theme-de-zu-zhi-jie-gou" style="visibility: hidden;"></a>
</h2>
<p>我注意到我此前并没有提示如何使用这些 Jekyll 主题，其实很简单：<code>cd your-jekyll-theme</code>、<code>bundler install</code>、<code>jekyll serve</code>，同样你可以在浏览器得到一个本地预览的版本。即便你使用的命令没有包含 <code>--watch</code> 选项，内容的构建仍然会是实时的。</p>
<p>我知道你已经受够了空荡荡的主题或是为了演示而填充的没意义的内容以及我的啰嗦，但请再稍稍忍耐一下，这里会谈到 Jekyll Theme 的组织结构和一些简单的内容组织方式，这将有助于你下一步修改/配置主题。</p>
<p>来吧，让我们用文件管理器或是你喜欢的文本编辑器打开你选定的主题所在的文件夹，看看里面有什么宝贝。</p>
<p>通常情况下，Jekyll Theme 会是下面所示的结构：</p>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>.</span></span>
<span class="giallo-l"><span>├── _config.yml</span></span>
<span class="giallo-l"><span>├── _drafts</span></span>
<span class="giallo-l"><span>| ├── begin-with-the-crazy-ideas.md</span></span>
<span class="giallo-l"><span>| └── sample-and-test.markdown</span></span>
<span class="giallo-l"><span>├── _includes</span></span>
<span class="giallo-l"><span>| ├── footer.html</span></span>
<span class="giallo-l"><span>| └── header.html</span></span>
<span class="giallo-l"><span>├── _layouts</span></span>
<span class="giallo-l"><span>| ├── default.html</span></span>
<span class="giallo-l"><span>| └── post.html</span></span>
<span class="giallo-l"><span>├── _posts</span></span>
<span class="giallo-l"><span>| ├── 2015-10-29-how-to-begin.textile</span></span>
<span class="giallo-l"><span>| └── 2013-04-26-hello-world.md</span></span>
<span class="giallo-l"><span>├── _data</span></span>
<span class="giallo-l"><span>| └── members.yml</span></span>
<span class="giallo-l"><span>├── _site</span></span>
<span class="giallo-l"><span>└── index.html</span></span></code></pre>
<ul>
<li>
<p><code>_config.yml</code></p>
<p>保存配置数据。很多配置选项都会直接从命令行中进行设置，但是如果你把那些配置写在这儿，你就不用非要去记住那些命令了。</p>
</li>
<li>
<p><code>_drafts</code></p>
<p>drafts 是未发布的文章。这些文件的格式中都没有 <code>title.MARKUP</code> 数据。</p>
</li>
<li>
<p><code>_includes</code></p>
<p>你可以加载这些包含部分到你的布局或者文章中以方便重用。可以用 <code>{% raw %}{% include file.ext %}{% endraw %}</code> 来把文件 <code>_includes/file.ext</code> 包含进来。</p>
</li>
<li>
<p><code>_layouts</code></p>
<p>layouts 是包裹在文章外部的模板。布局可以在 YAML 头信息中根据不同文章进行选择。标签 <code>{% raw %}{{ content }}{% endraw %}</code> 可以将 content 插入页面中。</p>
</li>
<li>
<p><code>_posts</code></p>
<p>这里放的就是你的文章了。文件格式很重要，必须要符合 <code>YEAR-MONTH-DAY-title.MARKUP</code>。The permalinks 可以在文章中自己定制，但是数据和标记语言都是根据文件名来确定的。</p>
</li>
<li>
<p><code>_data</code></p>
<p>格式良好的网站数据应该放在这里。Jekyll 引擎将自动加载此目录中的所有 yaml 文件（以 <code>.yml</code> 或 <code>.yaml</code> 结尾的文件）。如目录下有 <code>member.yml</code> 文件，则可以通过 <code>site.data.members</code> 访问该文件的内容。</p>
</li>
<li>
<p><code>_site</code></p>
<p>一旦 Jekyll 完成转换，就会将生成的页面放在这里（默认）。最好将这个目录放进你的 <code>.gitignore</code> 文件中。</p>
</li>
<li>
<p><code>index.html</code> 和其它 HTML、Markdown、Textile 文件</p>
<p>如果这些文件中包含 YAML 头信息部分，Jekyll 就会自动将它们进行转换。当然，其他的如 <code>.html</code>、<code>.markdown</code>、<code>.md</code>、或者 <code>.textile</code> 等在你的站点根目录下或者不是以上提到的目录中的文件也会被转换。</p>
</li>
<li>
<p>其它文件/文件夹</p>
<p>其他一些未被提及的目录和文件如 css 还有 images 文件夹，favicon.ico 等文件都将被完全拷贝到生成的 site 中。</p>
</li>
</ul>
<p>是的，这里搬运了 Jekyll 官方网站的内容，因为它们已经被介绍的很详尽。我不愿意做一些重复的工作。</p>
<p>我会在下一部分结合实例来讲一下各个部分的使用。</p>
<h2 id="yi-xie-di-san-fang-fu-wu-he-ge-xing-hua-pei-zhi">一些第三方服务和个性化配置<a class="zola-anchor" href="#yi-xie-di-san-fang-fu-wu-he-ge-xing-hua-pei-zhi" aria-label="Anchor link for: yi-xie-di-san-fang-fu-wu-he-ge-xing-hua-pei-zhi" style="visibility: hidden;"></a>
</h2>
<h3 id="chang-gui">常规<a class="zola-anchor" href="#chang-gui" aria-label="Anchor link for: chang-gui" style="visibility: hidden;"></a>
</h3>
<p>用你最喜爱的文本编辑器打开你的 Jekyll Theme，首先我们需要编辑 <code>_config.yml</code> 文件，通常情况下，它会包含一些网站所必须的 SEO 信息，以及你一些个人信息，按照你的情况把它填好，如果里面没有你所需要的内容请留空。社交链接和默认的第三方服务通常是在这里进行配置。</p>
<p>哦，我想我们不需要那些为了展示而配备的文章，如果你恰恰和我一样使用 <code>Fedora with Gnome</code>（我只是不确定其它系统的情况）我建议你将它们移动到 <code>模板</code> 文件夹中，这样你就可以按它的格式新建文章。</p>
<p>让我们来看一下用于文章的 <code>.markdown(.md)</code> 文件与平时有什么不同，这里给出一个示例：</p>
<pre class="giallo z-code"><code data-lang="markdown"><span class="giallo-l"><span>---</span></span>
<span class="giallo-l"><span class="z-entity z-name z-tag">t</span><span class="z-entity z-name z-tag">itle</span><span>:</span><span class="z-string"> E</span><span class="z-string">lements</span></span>
<span class="giallo-l"><span class="z-entity z-name z-tag">d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> M</span><span class="z-string">arkdown-How-To</span></span>
<span class="giallo-l"><span class="z-entity z-name z-tag">d</span><span class="z-entity z-name z-tag">ate</span><span>:</span><span class="z-constant"> 2013-12-24 23:29:08</span></span>
<span class="giallo-l"><span class="z-entity z-name z-tag">c</span><span class="z-entity z-name z-tag">ategories</span><span>:</span></span>
<span class="giallo-l"><span> -</span><span class="z-string"> F</span><span class="z-string">oo</span></span>
<span class="giallo-l"><span class="z-entity z-name z-tag">t</span><span class="z-entity z-name z-tag">ags</span><span>:</span></span>
<span class="giallo-l"><span>---</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>The purpose of this post is to help you make sure all of HTML elements can display properly. If you use CSS reset, don't forget to redefine the style by yourself.</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-meta z-separator">---</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">#</span><span class="z-entity z-name"> Heading 1</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">##</span><span class="z-entity z-name"> Heading 2</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">###</span><span class="z-entity z-name"> Heading 3</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">####</span><span class="z-entity z-name"> Heading 4</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">#####</span><span class="z-entity z-name"> Heading 5</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">######</span><span class="z-entity z-name"> Heading 6</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-meta z-separator">---</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">##</span><span class="z-entity z-name"> Paragraph</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>Lorem ipsum dolor sit amet, </span><span>[</span><span class="z-string z-other z-link">test link</span><span>]</span><span>(</span><span>)</span><span> consectetur adipiscing elit. </span><span class="z-markup z-bold">**</span><span class="z-markup z-bold">Strong text</span><span class="z-markup z-bold">**</span><span> pellentesque ligula commodo viverra vehicula. </span><span class="z-markup z-italic">*</span><span class="z-markup z-italic">Italic text</span><span class="z-markup z-italic">*</span><span> at ullamcorper enim. Morbi a euismod nibh. </span><span><</span><span class="z-entity z-name z-tag">u</span><span>></span><span>Underline text</span><span></</span><span class="z-entity z-name z-tag">u</span><span>></span><span> non elit nisl. </span><span>~~</span><span>Deleted text</span><span>~~</span><span> tristique, sem id condimentum tempus, metus lectus venenatis mauris, sit amet semper lorem felis a eros.</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>Interdum et malesuada fames ac ante ipsum primis in faucibus. </span><span class="z-markup z-inline z-raw">`</span><span class="z-markup z-inline z-raw">Sed erat diam</span><span class="z-markup z-inline z-raw">`</span><span>, blandit eget felis aliquam, rhoncus varius urna.</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-quote">></span><span class="z-markup z-quote"> Praesent diam elit, interdum ut pulvinar placerat, imperdiet at magna.</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">##</span><span class="z-entity z-name"> List Types</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">###</span><span class="z-entity z-name"> Definition List</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span><</span><span class="z-entity z-name z-tag">dl</span><span>></span><span><</span><span class="z-entity z-name z-tag">dt</span><span>></span><span>Definition List Title</span><span></</span><span class="z-entity z-name z-tag">dt</span><span>></span><span><</span><span class="z-entity z-name z-tag">dd</span><span>></span><span>This is a definition list division.</span><span></</span><span class="z-entity z-name z-tag">dd</span><span>></span><span></</span><span class="z-entity z-name z-tag">dl</span><span>></span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">###</span><span class="z-entity z-name"> Ordered List</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-list z-begin z-markdown">1.</span><span> List Item 1</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-list z-begin z-markdown">2.</span><span> List Item 2</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-list z-begin z-markdown">3.</span><span> List Item 3</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">###</span><span class="z-entity z-name"> Unordered List</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-list z-begin z-markdown">-</span><span> List Item 1</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-list z-begin z-markdown">-</span><span> List Item 2</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-list z-begin z-markdown">-</span><span> List Item 3</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-markup z-heading">##</span><span class="z-entity z-name"> Table</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>|</span><span> Table Header 1</span><span> |</span><span> Table Header 2</span><span> |</span><span> Table Header 3</span><span> |</span></span>
<span class="giallo-l"><span>|</span><span> ---</span><span> |</span><span> ---</span><span> |</span><span> ---</span><span> |</span></span>
<span class="giallo-l"><span>|</span><span> Division 1</span><span> |</span><span> Division 2</span><span> |</span><span> Division 3</span><span> |</span></span>
<span class="giallo-l"><span>|</span><span> Division 1</span><span> |</span><span> Division 2</span><span> |</span><span> Division 3</span><span> |</span></span>
<span class="giallo-l"><span>|</span><span> Division 1</span><span> |</span><span> Division 2</span><span> |</span><span> Division 3</span><span> |</span></span></code></pre>
<p>此文章来自 NexT 主题，介绍了基本的 Markdown 用法，你可以对照页面来看，最前面被一组 <code>---</code> 包围的内容属于 YAML，包含了文档的信息：标题，描述，分类，标签，日期；我建议你为每篇文章添加这些内容来记录。</p>
<p>你可能还需要修改关于介绍博主的内容，一部分主题会在 <code>_config.yml</code> 中进行集成，还有一部分主题会包含一个名为 <code>about/resume</code> 的文档，请把里面的内容换成你自己的。还有一种会使用 <code>_data</code> 文件夹内的数据或是引入 <code>_include</code> 文件夹中的内容，也同样请你修改它们，语法很简单，不做赘述。</p>
<p>这样你就可以把信息完全替换成你自己的，但我建议你保留页脚的部分信息，该内容通常会申明你使用的是什么主题。</p>
<h3 id="di-san-fang-fu-wu">第三方服务<a class="zola-anchor" href="#di-san-fang-fu-wu" aria-label="Anchor link for: di-san-fang-fu-wu" style="visibility: hidden;"></a>
</h3>
<p>啊哦，其实我有点担心是不是描述的足够清楚，如果有什么疑问的话请直接联系我。这一部分会介绍到如何加入第三方服务。</p>
<p>来看看我们需要哪些第三方服务：</p>
<ol>
<li>评论
<ul>
<li>多说</li>
<li>Disqus</li>
<li>来必力</li>
</ul>
</li>
<li>统计/SEO
<ul>
<li>百度</li>
<li>谷歌</li>
</ul>
</li>
</ol>
<p>这里以来必力和谷歌分析为例，选用这两个的原因只是因为方便，你可以自由选择适合你情况的服务。</p>
<h4 id="qi-yong-gu-ge-fen-xi-cha-jian">启用谷歌分析插件<a class="zola-anchor" href="#qi-yong-gu-ge-fen-xi-cha-jian" aria-label="Anchor link for: qi-yong-gu-ge-fen-xi-cha-jian" style="visibility: hidden;"></a>
</h4>
<p>先说谷歌分析吧，它通常在各个主题之中都有良好的支持，你需要的只是填入它提供的 ID，当然，你需要一个独立的域名来做这件事，还需要番茄 :( 如果你想要使用百度分析，可能需要为域名进行备案，此外，百度的搜索引擎似乎是在 GitHub 的黑名单上。</p>
<p>我这里默认你已经有了域名，也做了番茄，如果你需要注册域名，腾讯阿里都可以提供服务。</p>
<p>打开 Google Analytics，按照提示进行操作，在执行完所有步骤之后，你会得到一个类似 <code>xx-xxxx-xxxx</code> 的字符串，如果没有，请从给出的 Javascript 代码中把它找出来，复制粘贴到 <code>_config.yml</code> 中合适的位置。</p>
<p>很简单不是吗？以这个为例子主要是为了展示它的运作模式。主题通常会通过 Liquid 条件判断检查你在 <code>_config.yml</code> 中是否填写了 <code>ga_track_id</code>，然后把对应的 id 和 domain 填入位置。</p>
<p>这类代码通常位于 <code>_include/footer.html</code>，在 Huxblog 中，你可以在 <code>_layout/default.html</code> 找到 <code>{% raw %}{% include footer.html %}{% endraw %}</code> 这个语句，使我们可以把 <code>footer.html</code> 包含在页面中。</p>
<h4 id="an-zhuang-lai-bi-li-ping-lun-cha-jian">安装来必力评论插件<a class="zola-anchor" href="#an-zhuang-lai-bi-li-ping-lun-cha-jian" aria-label="Anchor link for: an-zhuang-lai-bi-li-ping-lun-cha-jian" style="visibility: hidden;"></a>
</h4>
<p>我知道这个第三方评论很少见，但鉴于天朝的环境，如果你想和小伙伴愉快发言，可以考虑一下。</p>
<p>打开 livere.com 按流程注册安装（我不想过多的描述这些没有意义的内容），你会得到一段 js 代码。</p>
<ul>
<li>如果你只打算自己用，请直接把它粘贴到 <code>_layout/post.html</code> 中合适的位置。通常这是对应你博文所使用的模板。</li>
<li>如果你打算把它做成插件，我建议你在 <code>_include</code> 中新建一个 <code>livere.html</code> 然后把它粘贴进去，将 <code>data-uid</code> 后面引号的内容换成 <code>{% raw %}{{ site.livere_uid }}{% endraw %}</code>，然后在 <code>_config.yml</code> 中合适的位置新建一行 <code>livere_uid: <your-data-uid></code>，在 <code>_layout/post.html</code> 中添加 <code>{% raw %}{% if site.livere_uid %}{{ include livere.html }}{% endif %}{% endraw %}</code>。</li>
<li>如果你想要通过博客的 <code>markdown</code> 文件中的信息头来控制，请按 <code>{% raw %}{% if page.comments == true %}{% if site.livere_uid %}{{ include livere.html }}{% endif %}{% endif %}{% endraw %}</code> 的样式添加到 <code>post.html</code> 中，这样，你只需要在博文信息头中加入 <code>comments: true</code> 就可以使它正常工作。</li>
</ul>
<p><strong>本来打算再讲一些其它的内容，一想我拖的时间有些长，而方法都大同小异，以后有需要再补。</strong></p>
<h2 id="jiang-ni-de-ye-mian-fa-bu">将你的页面发布 :)<a class="zola-anchor" href="#jiang-ni-de-ye-mian-fa-bu" aria-label="Anchor link for: jiang-ni-de-ye-mian-fa-bu" style="visibility: hidden;"></a>
</h2>
<p>本地预览确实很没意思，毕竟只是自娱自乐，还是早点发布比较好，你也不用再在我这里花费更多的时间了。</p>
<p>相信你应该还找得到你在开始创建的 <code>yourusername.github.io</code> 存储库，现在我们要把你本地的 <code>your-jekyll-theme</code> 中的内容上传到那里。</p>
<p>一个很直接的方式就是点击存储库的 <code>Upload</code> 按钮，然后将内容统统拖拽进去。</p>
<p>我觉得这已经足够你完成这项工作，享受你的博客吧。</p>
<p>PS：如果我现在说你直接 <code>fork</code> 一个别人的主题存储库，然后把存储库的名字和内容进行修改就可以得到属于你的网站，你会不会打死我。</p>