开发工具 on KnightLi的博客

Obsidian 和 Joplin 怎么选？Markdown 笔记工具对比指南

Sat, 30 May 2026 14:43:56 +0800

Obsidian 和 Joplin 都是 Markdown 笔记工具，但适合的人群不太一样。

简单说：Obsidian 更适合深度知识管理、双链卡片盒笔记和高度自定义的用户；Joplin 更适合注重数据隐私、需要全平台同步、偏向传统文件夹分类和网页剪藏的实用型用户。

如果你想搭建“第二大脑”、写长期研究笔记、折腾插件和知识图谱，优先看 Obsidian。如果你想找一个更安全、更自由的 Evernote / 有道云笔记替代品，优先看 Joplin。

核心差异对比

对比维度	Obsidian	Joplin
开源属性	闭源，个人免费，商业使用收费	完全开源，AGPL-3.0 license
数据存储	本地 `.md` 纯文本文件	本地数据库管理，笔记内容使用 Markdown
数据可控性	文件直接在本地文件夹中，迁移和备份直观	需要通过应用或导出功能管理，但支持加密和同步
官方同步	Obsidian Sync，付费	Joplin Cloud，付费
免费同步	需要第三方方案，例如 iCloud、Git、坚果云、Syncthing 等	内置支持 OneDrive、Dropbox、WebDAV、文件系统等同步目标
核心优势	双向链接、知识图谱、插件生态、强自定义	网页剪藏、端到端加密、跨平台同步、开源
组织方式	关系网络、双链、标签、文件夹	笔记本、子笔记本、笔记、标签
上手体验	功能强，但容易越用越复杂	更接近传统笔记应用，上手更直接

数据管理与隐私

Obsidian 的特点是“文件即数据”。你的笔记就是一个个普通 .md 文件，直接保存在本地文件夹中。即使将来不用 Obsidian，也可以用任意文本编辑器打开这些文件。

这种方式的优势是直观、开放、便于备份，也适合用 Git 管理。缺点是同步、附件管理和多端一致性需要用户自己规划。

Joplin 同样使用 Markdown 语法，但笔记由应用数据库管理。它的优势是功能更完整，笔记、附件、标签、同步状态都由应用统一处理。Joplin 还原生支持端到端加密（E2EE），配合第三方网盘同步时，云服务商也难以直接读取笔记内容。

如果你更看重“我的笔记就是本地文件”，Obsidian 更顺手。如果你更看重“应用帮我管理同步、加密和附件”，Joplin 更省心。

同步方案与成本

Obsidian 的官方同步服务是 Obsidian Sync，体验好，但需要付费。如果想免费在手机、平板和电脑之间同步，就要自己配置第三方方案，例如 iCloud、Git、Syncthing、坚果云或其他 WebDAV 方案。这对熟悉文件同步的人问题不大，但对新手有门槛。

Joplin 的同步更偏内置能力。它支持 Joplin Cloud，也支持 OneDrive、Dropbox、WebDAV、文件系统等同步目标。只要绑定账号或配置地址，就可以在多端之间同步笔记。

需求	更适合
愿意为官方同步付费，想要省心体验	Obsidian Sync 或 Joplin Cloud 都可以
想免费使用第三方网盘同步	Joplin 更直接
熟悉 Git / Syncthing / iCloud，并愿意折腾	Obsidian 也很好用
希望同步时启用端到端加密	Joplin 更内置

插件生态与自定义

Obsidian 的插件生态是它最强的部分之一。通过插件，它可以变成任务看板、闪卡工具、日历、思维导图、个人数据库，甚至接近一个本地知识系统。

双向链接、反向链接、局部图谱和 Dataview 这类插件，能让零散笔记逐渐形成知识网络。对写书、研究、知识卡片、项目资料沉淀来说，这种能力非常有吸引力。

Joplin 也支持插件、主题和一些链接能力，但生态丰富度和折腾空间不如 Obsidian。它的好处是更克制，不容易让用户把大量时间花在改界面、换主题和试插件上。

如果你的目标是“深度定制知识管理系统”，Obsidian 更强。如果你的目标是“稳定记录、同步和搜索”，Joplin 已经够用。

网页剪藏能力

网页剪藏是 Joplin 的强项。它提供官方 Web Clipper，可以从浏览器保存网页、简化文章内容、截取页面或保存链接。对于收集离线资料、保存技术文章和整理网页内容的人来说，这个功能很实用。

Obsidian 原生网页剪藏能力相对弱，通常需要依赖第三方浏览器扩展或其他工作流。可用方案不少，但体验和稳定性取决于插件与网页结构，剪藏后也可能需要手动整理排版。

场景	更适合
高频保存网页文章	Joplin
做离线资料库	Joplin
只偶尔保存网页链接	两者都可以
保存后还要深度改写、双链整理	Obsidian

组织方式差异

Obsidian 更像一个以本地文件夹为基础的知识网络。你可以用文件夹整理，也可以用标签、双链、反向链接和图谱组织知识。它适合非线性笔记和主题之间关系复杂的知识库。

Joplin 更像传统笔记软件。它采用笔记本、子笔记本、笔记的层级结构，也支持标签。对习惯 Evernote、有道云笔记、OneNote 这类工具的人来说，Joplin 的组织方式更熟悉。

偏好	推荐
喜欢文件夹 + 双链 + 图谱	Obsidian
喜欢笔记本 + 子笔记本 + 标签	Joplin
做学术研究、写书、卡片盒	Obsidian
做资料收集、项目笔记、网页归档	Joplin

你应该选哪个

选择 Obsidian，如果：

你在做长期研究、写书、课程资料整理或个人知识库。
你重视双向链接、反向链接和知识图谱。
你希望高度定制界面、快捷键、插件和工作流。
你愿意花时间折腾同步、插件和文件结构。
你希望笔记直接作为本地 Markdown 文件存在。

选择 Joplin，如果：

你想要一个开源、跨平台、可同步的传统笔记应用。
你重视端到端加密和数据隐私。
你经常使用网页剪藏保存文章。
你不想为基础同步付费，也不想折腾复杂同步方案。
你更习惯笔记本、子笔记本、标签这种传统结构。

简单结论

Obsidian 和 Joplin 不是谁绝对更好，而是设计目标不同。

Obsidian 更像一个可高度定制的 Markdown 知识管理平台，适合愿意搭系统、做双链、玩插件的人。它的上限很高，但也容易让人陷入“搭建系统比写笔记更开心”的状态。

Joplin 更像一个开源、可同步、可加密的传统笔记应用，适合想稳定记录、网页剪藏、多端同步和长期保存资料的人。它没有 Obsidian 那么强的双链生态，但更接近“装好就能认真记笔记”的工具。

一句话：想搭第二大脑，选 Obsidian；想要开源版 Evernote，选 Joplin。

Joplin：离线优先、支持同步和加密的开源笔记应用

Sat, 30 May 2026 14:39:48 +0800

Joplin 是一个开源笔记与待办应用，支持 Windows、macOS、Linux、Android 和 iOS。它的定位不是轻量便签，而是一个可以长期保存大量笔记、同步到多设备、并尽量让数据掌握在用户手里的知识管理工具。

Joplin 的笔记使用 Markdown 格式，支持笔记本、标签、全文搜索、附件、待办事项、插件、主题和浏览器 Web Clipper。对于想从 Evernote 迁移出来，或者想用更开放格式管理个人资料的人来说，它是很常见的选择。

Joplin 解决什么问题

很多笔记应用用起来方便，但数据容易被锁在某个账号、某个云服务或某种私有格式里。Joplin 的思路更偏开放：本地保留完整数据，笔记正文使用 Markdown，再通过用户选择的同步目标在多设备之间同步。

它适合下面几类需求：

想把笔记长期保存为 Markdown。
想在电脑和手机之间同步笔记。
想从 Evernote 导入旧笔记和附件。
想使用端到端加密同步。
想用插件和主题扩展笔记应用。
想把网页内容快速剪藏到自己的笔记库。

核心特性速查

特性	说明
开源	仓库公开，项目长期维护，许可证为 AGPL-3.0 license
跨平台	支持 Windows、macOS、Linux、Android、iOS
Markdown	笔记正文使用 Markdown，便于阅读、迁移和长期保存
离线优先	本地始终保存数据，没有网络也能查看和编辑
同步	支持多种同步目标，包括 Joplin Cloud、Nextcloud、Dropbox、OneDrive 等
端到端加密	同步时可以启用 E2EE，降低云端存储风险
导入	支持从 Evernote 导入，也支持普通 Markdown 文件导入
扩展	支持插件、主题和 Web Clipper

离线优先是什么意思

Joplin 官方 README 中强调它是 “offline first”。这意味着笔记不是只存在于云端，而是保存在本机或手机上。即使没有网络，也能打开、搜索和编辑已有笔记。

这个设计对笔记工具很重要。网络不好、同步服务临时不可用、或者账号服务出现问题时，本地仍然有完整数据。同步只是让多设备保持一致，而不是把所有使用体验都绑定到云端。

Markdown 与导入能力

Joplin 的笔记使用 Markdown，这让它比完全私有格式更容易迁移和备份。用户可以直接导入普通 Markdown 文件，也可以从 Evernote 导入笔记。

Evernote 导入时，Joplin 会尝试转换格式化内容，并保留资源文件，例如图片和附件，同时保留创建时间、更新时间、地理位置等元数据。对有多年 Evernote 资料的人来说，这一点比单纯复制文字更重要。

不过，任何跨应用迁移都不应该盲信“一键完成”。复杂排版、表格、附件、内部链接和标签结构都建议先用少量样本测试，再迁移完整资料库。

同步与加密

Joplin 支持多种同步方式。常见选择包括：

同步目标	适合场景
Joplin Cloud	想省心使用官方服务
Nextcloud	已经有自建云或团队协作环境
Dropbox	习惯使用 Dropbox 的个人用户
OneDrive	使用 Microsoft 生态的用户
文件系统 / WebDAV 等	想自己控制同步位置的人

同步可以配合端到端加密使用。启用后，笔记内容在同步到云端前会先加密，云服务更多只是保存加密后的数据。这样可以降低第三方云盘或同步服务泄露内容的风险。

加密也会带来管理成本。用户需要妥善保存密码和恢复信息，否则换设备或重装后可能无法解密旧笔记。

Web Clipper 与插件

Joplin 还提供浏览器 Web Clipper，用来从 Chrome、Firefox 等浏览器保存网页和截图。对做资料收集、网页剪藏和研究笔记的人来说，这是很实用的入口。

插件和主题则让 Joplin 更接近一个可扩展平台，而不是固定功能的笔记软件。用户可以根据自己的工作流扩展编辑、展示、搜索、导入导出等能力。

和 Obsidian 的区别

Joplin 和 Obsidian 都常被 Markdown 用户拿来比较，但两者侧重点不同。

维度	Joplin	Obsidian
主要定位	开源笔记与待办应用，内置同步方案和加密能力	本地 Markdown 知识库，强调双链、插件生态和图谱
数据组织	应用管理笔记本、标签、附件和数据库索引	直接围绕文件夹和 Markdown 文件工作
同步	内置多种同步目标和 E2EE	官方同步是付费服务，也可自行使用第三方同步
适合人群	想要开箱即用、跨端同步、兼顾隐私的人	想深度定制个人知识库和本地文件工作流的人

如果你想要一个“开源版 Evernote + Markdown + 同步加密”，Joplin 更贴近这个需求。如果你想围绕本地 Markdown 文件搭建高度定制的知识系统，Obsidian 可能更顺手。

适合谁使用

Joplin 适合几类用户：

想从 Evernote 迁移出来的人。
想把笔记保存为 Markdown 的用户。
需要 Windows、macOS、Linux、Android、iOS 多端同步的人。
关心隐私，希望启用端到端加密的人。
希望笔记软件开源、可自托管、可长期迁移的人。
需要网页剪藏和附件管理的人。

它不一定适合只想要极简便签的人。Joplin 功能较完整，配置同步、加密、插件和导入时，也需要花一点时间理解。

使用建议

如果你准备试用 Joplin，可以按这个顺序开始：

先在桌面端创建一个测试笔记本。
导入少量 Markdown 或 Evernote 样本。
检查图片、附件、标签、创建时间和格式是否正常。
再设置同步目标，例如 Joplin Cloud、Nextcloud、Dropbox 或 OneDrive。
如果要开启端到端加密，先确认所有设备都能正常同步和解密。
最后再迁移完整笔记库。

这样做比直接把多年笔记一次性导入更稳，也方便在正式迁移前发现格式或同步问题。

我的判断

Joplin 的优势在于把几个重要方向放在了一起：Markdown、开源、跨平台、离线优先、同步和端到端加密。它不只是一个写 Markdown 的编辑器，更像一个面向长期使用的个人笔记系统。

如果你希望笔记数据尽量开放，又不想完全自己拼同步、加密和移动端应用，Joplin 是很值得试的选择。它尤其适合从 Evernote 迁移、重视隐私、多设备使用，并希望以后仍能把数据迁走的用户。

项目链接：laurent22/joplin
官方文档：Joplin documentation

Jimmy：把 Evernote、Notion、Google Keep 等笔记导出转换成 Markdown

Sat, 30 May 2026 11:55:56 +0800

Jimmy 是一个笔记转换工具，目标是把不同笔记应用或文档格式里的内容转换成 Markdown。它适合想把笔记从封闭应用里迁出来、放进 Obsidian、Joplin，或者只想长期保存为纯文本的人。

项目文档里的定位很直接：导出或备份原笔记应用的数据，运行 jimmy 转换，再把结果导入 Joplin、Obsidian，或者直接用 VSCode 等文本编辑器查看。

Jimmy 解决什么问题

很多笔记应用都有自己的导出格式。换应用时，最麻烦的往往不是文字内容，而是图片、附件、标签、内部链接和 front matter 这些结构化信息。

Jimmy 做的事情就是把这些导出数据尽量整理成更通用的 Markdown 目录：

笔记正文转换为 Markdown。
尽量保留图片、资源和附件。
尽量保留标签、外部链接和笔记内部链接。
输出 Markdown + front matter。
结果可以导入 Joplin、Obsidian 等工具，也可以直接用文本编辑器查看。

这类工具的意义在于降低迁移成本。笔记一旦变成 Markdown，就不再强绑定某个应用，后续备份、搜索、版本管理和 LLM 处理都会简单很多。

支持的笔记应用很多

Jimmy 支持的来源覆盖面很广，包括 Anki、Anytype、Bear、CherryTree、ColorNote、Day One、Diaro、Drafts、Dynalist、Evernote、Google Docs、Google Keep、Joplin、Notion、Obsidian、OneNote、QOwnNotes、RedNotebook、Reflect、Roam Research、Signal、Simplenote、Standard Notes、Synology Note Station、Telegram、Tiddlywiki、Turtl、UpNote、Wordpress、Zim、Zoho Notebook 等。

并不是所有来源的保真度都完全一样。实际迁移时，仍然要先用一小批笔记试跑，重点检查图片、附件、标签、内部链接和日期字段是否符合预期。

也能转换普通文档

除了笔记应用导出，Jimmy 也能处理一些常见文档格式。文档中提到可以转换单个文件，也可以递归转换整个文件夹，适合把杂乱的资料目录整理成 Markdown。

常见支持格式包括：

类型	例子
办公文档	DOCX、ODT、RTF
标记语言	Asciidoc、DocBook、Markdown、MediaWiki、reStructuredText
网页与电子书	HTML、MHTML、EPUB
数据与结构化文件	CSV、OPML、Jupyter Notebook
其他	PDF、EML、Fountain、txt2tags

如果只是把 DOCX、PDF 或 HTML 批量转成 Markdown，Jimmy 也可以作为一个离线批处理工具来用。

两种使用方式

Jimmy 提供 CLI 和 TUI 两种界面。

界面	适合场景	说明
CLI	批处理、脚本、完整功能	适合一次性转换文件夹、写迁移脚本、指定来源格式
TUI	交互式转换	适合手动操作，目前功能子集仍处于 beta 状态

官方 README 给出的 Linux 示例命令如下：

# 使用交互式 TUI 转换
jimmy-linux tui

# 转换一个 pandoc 支持的单文件
jimmy-linux cli libre_office_document.odt

# 转换整个文件夹
jimmy-linux cli path/to/folder

# 转换 Google Keep 导出
jimmy-linux cli takeout-20240401T160516Z-001.zip --format google_keep

这些命令说明它不是只面向某一个笔记应用，而是把“笔记导出包”和“普通文档目录”都纳入了同一套转换流程。

它的几个特点

特点	说明
离线运行	转换过程不依赖云服务，适合处理私人笔记
开源	仓库采用 GPL-3.0 license
跨平台	官方提供 Linux、Windows、macOS 下载
独立二进制	不要求用户额外安装 Docker、Python 或 Node.js
不使用 AI	转换过程不调用 AI，结果更可控，也减少隐私顾虑
Markdown + front matter	方便导入笔记软件，也方便后续用 Git 管理

其中“离线”和“不使用 AI”很适合笔记迁移场景。笔记里经常有私人信息、工作资料和历史附件，把转换放在本地完成，会让风险边界更清楚。

适合谁使用

Jimmy 适合几类人：

想从 Evernote、Notion、OneNote、Google Keep 等工具迁移到 Markdown 的用户。
想把笔记导入 Obsidian、Joplin 或其他纯文本工作流的人。
想把长期资料保存为未来更容易读取格式的人。
想把笔记或文档准备成 LLM 可处理文本的人。
需要递归转换 DOCX、PDF、HTML、ODT 等文件夹资料的人。

它不一定适合追求“一键完美迁移”的用户。不同笔记应用导出格式差异很大，复杂页面、数据库、嵌入内容和内部链接都可能需要人工复查。

使用前的检查建议

真正迁移前，建议按这个顺序做：

先从原笔记应用导出一小批样本。
用 Jimmy 转换样本，而不是一上来转换全部笔记。
检查 Markdown 正文、图片、附件、标签、创建时间、内部链接。
确认目标应用，例如 Obsidian 或 Joplin，能正确识别目录结构和 front matter。
再对完整导出包执行转换。
保留原始导出包和转换结果，至少等确认无误后再清理。

这个流程虽然慢一点，但能避免迁移后才发现附件丢失、链接断掉或标签结构不对。

我的判断

Jimmy 的价值在于把笔记迁移从“依赖某个应用的导入器”变成“先转成通用 Markdown”。它支持的来源很多，输出也足够通用，适合把个人知识库从封闭格式里释放出来。

如果你只是偶尔导出一两篇笔记，可能用不到它。但如果你有多年积累的笔记、附件和文档目录，想迁移到 Obsidian、Joplin 或 Git 管理的 Markdown 工作流，Jimmy 很值得试。它最适合做迁移中间层：先把数据变成可读、可备份、可批处理的文本，再决定放进哪个笔记系统。

项目链接：marph91/jimmy
文档链接：Jimmy - Note Conversion Tool

Google Pay 与 Wallet 推出 Developer MCP Server：把支付集成接入 AI 助手

Fri, 29 May 2026 15:24:18 +0800

Google Developers 发布了 Google Pay 与 Wallet Developer MCP Server。它面向正在集成 Google Pay API 和 Google Wallet API 的开发者，把官方文档、账号状态、集成校验和部分业务指标接入 MCP 兼容的 AI 开发工具。

这类更新看起来不像模型发布那么热闹，但对开发者很实用。支付和钱包集成往往不是“会不会写代码”的问题，而是文档细节多、配置项多、审核要求多、错误反馈分散。MCP Server 的价值就在于让 AI 助手可以在更接近真实上下文的位置帮开发者排查问题。

它解决什么问题

开发者在接入 Google Pay 或 Google Wallet 时，通常要在多个地方来回切换：

查官方文档和示例代码
确认账号与商户配置
检查请求参数和返回错误
验证集成是否符合要求
观察调用表现和关键指标

如果只把这些内容当成网页文档，AI 助手最多只能解释概念或生成示例。接入 MCP Server 后，助手可以通过工具访问更具体的信息，从而给出更贴近当前项目状态的建议。

MCP 在这里为什么合适

MCP 的作用是给 AI 应用提供标准化工具接口。对 Google Pay 和 Wallet 这样的开发者产品来说，它非常适合处理“文档加状态加校验”的组合任务。

例如，开发者可以让支持 MCP 的 AI 工具帮助回答：

当前集成缺了哪些配置
某个 Google Pay 请求为什么失败
Wallet pass 定义里哪些字段可能不符合要求
代码示例应该如何改成当前业务需要的形态
集成上线前还需要检查哪些项目

这些问题如果只靠大模型记忆，风险很高；如果能结合官方工具和当前账号信息，回答就更可操作。

对 AI 编程工作流的意义

这次发布也说明一个趋势：AI 编程助手正在从“读代码”走向“读产品系统”。

过去，开发者让 AI 帮忙集成支付能力，通常只能把文档片段、错误日志和代码贴进去。AI 可以解释，但不一定知道当前集成的真实状态。MCP Server 把这部分能力向前推进了一步，让 AI 助手有机会直接围绕产品集成环境工作。

这对几类场景尤其有价值：

新项目首次接入 Google Pay 或 Wallet。
旧项目迁移到新的 API 或配置方式。
上线前做集成检查。
遇到错误码、审核问题或配置不一致时快速定位。

对团队来说，收益不只是少查几页文档，而是减少“文档理解正确，但配置现场不一致”的摩擦。

它不会替代开发者判断

支付和钱包相关集成有安全、合规和用户体验要求。MCP Server 可以帮助 AI 助手更快找到信息、检查状态、生成建议，但最终仍需要开发者确认代码、安全策略、商户配置和上线流程。

尤其是支付链路，不能因为 AI 给出一个看似合理的建议就直接上线。更稳妥的方式是把 MCP 工具当成检查员和导航员：它能缩短定位时间，但不能替代审核、测试和业务责任。

我的判断

Google Pay 与 Wallet Developer MCP Server 的意义不在于“又多了一个 MCP 示例”，而在于它把 MCP 放进了一个真实、复杂、强约束的开发者场景。

如果 MCP 只连接文档，它的价值有限；如果它能连接账号状态、集成校验、指标和产品后台，AI 助手就能承担更多实际开发工作。Google 这次发布正好展示了这个方向。

未来类似能力很可能会出现在更多云服务、广告平台、支付系统和企业 SaaS 里。开发者要适应的不是“AI 会写代码”，而是“AI 可以通过标准工具接口参与整个集成流程”。

原文链接：Supercharge your integration workflow with the Google Pay & Wallet Developer MCP Server

Remotion：用 React 以编程方式生成视频

Wed, 27 May 2026 14:39:22 +0800

remotion-dev/remotion 是一个用 React 以编程方式创建视频的框架。它把视频制作从传统时间轴工具里抽出来，变成可以用组件、状态、数据、API、CSS、Canvas、SVG、WebGL 和算法控制的前端工程问题。

项目地址：remotion-dev/remotion

这类工具很适合今天的 AI 编程工作流：如果一个 agent 能生成网页、图表和数据视图，它也可以继续生成视频脚本、动画组件和可渲染的短片。

Remotion 解决的是什么问题

传统视频工具擅长人工剪辑，但不擅长规模化、参数化和自动化。

比如这些任务：

给每个用户生成一条个性化年度回顾视频
根据数据库自动生成产品演示视频
把图表、代码片段和讲解字幕组合成技术短片
批量生成营销素材、社交媒体短视频或课程片段
用 CI/CD 或后端服务按需渲染视频

如果用传统剪辑软件，这些任务很难完全自动化。Remotion 的做法是把视频当成 React 应用来写：每一帧都是组件和数据在某个时间点的结果。

为什么是 React

Remotion README 里给出的理由很清楚：React 可以复用 Web 技术和组件化能力。

它让你可以使用：

CSS 做布局和动画
SVG 做矢量图形
Canvas 和 WebGL 做复杂绘制
JavaScript / TypeScript 做变量、函数、API 调用、数学和算法
React 组件做复用、组合和快速迭代

这意味着前端开发者不需要重新学习一套完全陌生的视频 DSL。很多已有的 UI、图表、设计系统和数据逻辑，都可以迁移到视频生成场景里。

快速开始

如果已经安装 Node.js，README 给出的入口命令是：

`1`	`npx create-video@latest`

创建项目后，你通常会编写 React 组件来描述画面，再让 Remotion 按帧渲染输出视频。

更完整的文档可以看：

文档：remotion.dev/docs
API Reference：remotion.dev/api

它适合哪些场景

Remotion 最适合“视频内容由数据或代码驱动”的场景。

个性化视频

例如年度回顾、用户成就、订单总结、学习报告。每个用户的数据不同，但视觉结构相同。用 React 组件加数据驱动，会比手工剪辑更自然。

技术演示视频

如果视频里包含代码、图表、产品界面、步骤动画和说明文字，Remotion 很适合把这些元素组织成可重复渲染的模板。

数据视频和图表动画

数据可视化本来就是前端强项。Remotion 让图表不仅可以出现在网页里，也可以按时间轴进入视频。

AI 生成视频工作流

AI agent 可以先生成脚本和素材结构，再生成 Remotion 组件，最后渲染视频。这比让模型直接生成最终视频更可控，因为中间产物是代码，可以检查、修改、版本管理和复用。

对 AI 编程工具的意义

Remotion 对 Codex、Claude Code、Cursor、Gemini CLI 这类 AI 编程工具特别有意思。

原因是视频生成被拆成了开发任务：

生成 React 组件。
调整样式和布局。
接入数据。
预览画面。
根据反馈修改。
渲染输出。

这套流程非常适合 agent：每一步都有文件、有代码、有预览、有明确反馈。相比“直接生成一个视频文件”，代码化视频更容易被审阅和迭代。

如果再结合浏览器侧边栏、截图检查、自动化渲染和评论反馈，Remotion 可以成为 AI 工作流里的视频产物层。

使用前要注意许可

Remotion README 特别提醒：Remotion 有特殊许可，在某些公司使用场景下需要获得 company license。

所以不要只把它当成普通 MIT 小工具来用。个人项目、开源项目、商业项目、企业内部工具，许可要求可能不同。正式用于公司生产前，应该先阅读它的 LICENSE 页面和官方许可说明。

这点很重要，尤其是把 Remotion 接进自动化内容生成、营销素材生成或企业内部视频流水线时。

我的判断

Remotion 的价值不只是“用 React 做视频”，而是把视频变成可编程、可复用、可自动化的产物。

对普通前端团队来说，它适合做数据驱动的视频模板。对 AI 工具来说，它更像一个稳定的输出目标：模型不需要一次性生成黑盒视频，而是生成可读、可改、可渲染的 React 代码。

如果你的内容需要批量生成、个性化生成、根据数据更新，或者需要让 agent 反复调整视觉细节，Remotion 值得放进工具箱里。它不是传统剪辑软件的替代品，而是把视频生产接入软件工程流程的一种方式。

CLIProxyAPI Management Center：给 CLIProxyAPI 配一个可视化管理后台

Sun, 24 May 2026 10:05:15 +0800

Cli-Proxy-API-Management-Center 可以理解成 CLIProxyAPI 的“驾驶舱”。

前一篇提到的 CLIProxyAPI 负责把 Gemini CLI、Codex、Claude Code、OpenRouter 等能力代理成统一 API；而这个 Management Center 解决的是另一个问题：

代理服务跑起来之后，配置、账号、OAuth、日志、配额和凭据，总不能全靠手改文件和翻终端吧？

所以它提供了一个 Web 管理界面，让你可以用浏览器管理 CLIProxyAPI 的配置与运行状态。

它是什么

从项目说明看，Cli-Proxy-API-Management-Center 是 CLIProxyAPI 的独立管理前端，核心功能包括：

可视化编辑 CLIProxyAPI 配置。
上传和管理 auth.json 一类认证文件。
查看请求日志和模型响应日志。
管理 OAuth 认证流程。
检查 Gemini CLI 账号配额。
提供账号、配置、日志等日常维护入口。

另外，官方仓库也提示：新版 CLIProxyAPI 已经内置了这个管理界面，可以直接通过 /management.html 访问；独立仓库仍然保留给需要单独部署或二次开发的人使用。

这点很重要。也就是说，大多数普通用户未必需要额外部署这个仓库；先确认你的 CLIProxyAPI 版本是否已经自带管理页。

它解决的不是“调用模型”，而是“管理模型入口”

CLIProxyAPI 的难点不只是能不能把请求转到模型。

真正麻烦的是这些东西：

多个 Gemini、OpenAI、Claude、Codex 账号如何放进池子里。
哪个账号已经失效，哪个账号配额快用完。
OAuth 登录态怎么导入、刷新和排查。
配置文件怎么改才不会漏逗号、漏字段。
请求到底打到了哪个 provider、哪个模型、哪个账号。
失败请求是上游问题、协议问题，还是本地配置问题。

Management Center 的价值就在这里：它把“代理基础设施”的日常维护变成可视化操作。

如果你只是本机跑一个账号、偶尔调几次 API，它不一定是刚需；但只要你开始做多账号、多模型、多客户端接入，一个后台界面就会明显省事。

典型使用场景

第一，管理账号池。

CLIProxyAPI 支持多账号轮询和负载均衡，但账号越多，越不适合靠手工翻配置文件维护。管理中心可以帮助你查看账号状态、导入凭据、排查异常账号。

第二，排查请求失败。

当客户端报错时，你需要知道请求有没有进代理、走了哪个 provider、返回了什么错误。日志界面比在终端里滚屏找错误舒服很多。

第三，处理 OAuth。

Codex、Claude Code、Gemini CLI 这类工具经常涉及 OAuth 登录态。管理中心提供 OAuth 相关操作入口，能减少重复命令行操作。

第四，给团队内部使用。

如果 CLIProxyAPI 变成团队共享网关，那管理者需要一个能快速查看配置和状态的界面。否则每次变更都要登录服务器改文件，效率很低，也容易误操作。

和 CLIProxyAPI 的关系

可以把两者分成前后两层：

客户端 / IDE / 脚本
        |
        v
CLIProxyAPI：负责协议代理、账号池、模型路由
        |
        v
Gemini CLI / Codex / Claude Code / OpenRouter / 上游模型

Management Center 不在这条推理请求链路的核心位置。它更像运维面板：

浏览器
  |
  v
Management Center：编辑配置、看日志、管账号、查配额
  |
  v
CLIProxyAPI 管理接口 / 配置 / 日志 / 凭据

所以不要把它理解成另一个模型代理。它是管理 CLIProxyAPI 的工具，不是替代 CLIProxyAPI 的工具。

为什么新版内置后仍然值得单独看

既然 CLIProxyAPI 已经内置了 /management.html，为什么还要关注这个独立仓库？

主要有三个原因。

第一，独立仓库能让你看清管理中心本身的功能边界。哪些是前端负责的，哪些必须由 CLIProxyAPI 后端提供接口，一眼更清楚。

第二，如果你要二次开发，比如改 UI、加鉴权、接自己的监控系统，独立仓库更适合作为入口。

第三，如果你的部署环境比较特殊，比如前后端分开部署、管理页走单独域名、静态资源由内网网关托管，独立版本更灵活。

对普通个人用户来说，优先用 CLIProxyAPI 内置版就够了；对团队或深度定制用户，独立仓库更有意义。

部署时最该注意什么

管理后台接触的是敏感东西：账号、OAuth、API Key、日志、请求内容、上游配额。

所以第一条原则是：不要把管理页面裸露到公网。

比较稳的做法是：

只允许本机访问，比如绑定 127.0.0.1。
如果必须远程访问，放到 VPN、Tailscale、内网跳板机或反向代理鉴权后面。
给管理接口加认证，不要只靠“地址没人知道”。
日志里尽量避免暴露完整 Key、Cookie、OAuth token 和用户原始请求。
团队环境里要分清“调用 API 的人”和“能改配置的人”。

很多代理工具真正出问题，不是模型调用失败，而是管理口、日志和凭据文件没保护好。

它适合和哪些东西一起用

如果你只部署 CLIProxyAPI，一个管理中心已经能解决基础维护问题。

如果你进一步关心统计和可观测性，还可以搭配 CLIProxyAPI 生态里的其他工具：

CPA Usage Keeper：偏用量同步和 SQLite 存储。
CLIProxyAPI Usage Dashboard：偏本地优先的用量、配额和图表展示。
CPA-Manager：偏完整管理中心，关注请求监控、费用估算、账号巡检和异常账号清理建议。

可以简单理解：

Management Center 管“配置和日常维护”。
Usage Dashboard 管“看用量和配额”。
CPA-Manager 管“更重的运营和巡检”。

实际用哪个，要看你的部署规模。个人本机用不需要把全家桶都装上。

使用建议

如果你刚开始折腾 CLIProxyAPI，可以按这个顺序来：

先让 CLIProxyAPI 本体跑通，确认 API 能正常响应。
打开内置的 /management.html，看看配置和日志是否能正常读取。
再导入一个账号或一个 provider，确认管理界面能反映状态变化。
有公网访问需求时，先做认证和网络隔离，再考虑开放入口。
等账号和请求量变多，再补用量统计和更完整的管理工具。

不要一开始就把所有账号、所有 provider、所有管理组件一次性接上。越是代理和账号池类项目，越适合小步验证。

总结

Cli-Proxy-API-Management-Center 的定位很清楚：它不是模型、不是聊天客户端，也不是新的 API 网关；它是 CLIProxyAPI 的可视化管理层。

当 CLIProxyAPI 只是一个本机小工具时，你可以不用它；当 CLIProxyAPI 开始承载多账号、多模型、多客户端调用时，它就会变成很实用的“控制台”。

真正要注意的是安全边界。管理后台能改配置、看日志、碰凭据，一旦暴露不当，风险比普通 API 调用口还高。把它放在可信网络里，用认证保护好，再去享受可视化管理带来的省心。

参考资料：

CLIProxyAPI：把 Codex、Claude Code、Gemini CLI 统一封装成 API

Sun, 24 May 2026 10:03:33 +0800

CLIProxyAPI 是一个很有“民间工程味”的项目：它不是再造一个大模型，也不是单纯做 API 转发，而是把一堆原本偏交互式、偏 CLI、偏 OAuth 登录的 AI 工具，重新包成统一 API 服务。

它支持的对象包括 Gemini CLI、OpenAI Codex、Claude Code、Amp CLI、AI Studio Build，以及上游 OpenAI 兼容服务。换句话说，它想解决的问题是：

我手上有 CLI 工具、有订阅账号、有 OAuth 登录态，能不能像调用普通 API 一样，把这些能力接到自己的客户端、脚本、IDE 或内部服务里？

CLIProxyAPI 给出的答案是：可以，中间加一层代理，把不同来源的 CLI 能力转换成 OpenAI、Gemini、Claude、Codex 兼容接口。

它真正解决的痛点

很多 AI 编程工具的能力本来很强，但默认使用方式并不适合自动化。

比如：

Gemini CLI 能登录账号使用，但你的程序更习惯调用 HTTP API。
Claude Code 很适合交互式编码，但接入其他客户端时会遇到协议不一致。
Codex CLI 支持 OAuth 登录和 Responses 风格能力，但不是所有上层工具都知道怎么和它说话。
一个团队可能有多个账号，需要轮询、负载均衡、异常账号剔除和配额观察。
你想让某些工具只认 OpenAI 格式，但后端实际可能是 Gemini、Claude 或 Codex。

CLIProxyAPI 的定位，就是做这些工具和客户端之间的“协议适配层”。

它把复杂的一侧藏在后面：OAuth、CLI 登录、多账号、不同协议、不同 provider。前面则暴露相对熟悉的接口，比如 OpenAI Chat Completions、OpenAI Responses、Gemini、Claude Messages、Codex 相关端点。

能力概览

从官方 README 和文档看，CLIProxyAPI 目前的核心能力包括：

为 CLI 模型提供 OpenAI、Gemini、Claude、Codex 兼容 API 端点。
通过 OAuth 登录接入 OpenAI Codex 和 Claude Code。
支持流式、非流式响应，以及部分场景下的 WebSocket。
支持函数调用、工具调用和多模态输入。
支持 Gemini、OpenAI、Claude 多账号轮询与负载均衡。
支持 Gemini AI Studio API Key。
支持 AI Studio Build、Gemini CLI、Claude Code、OpenAI Codex 的多账号池。
可以通过配置接入 OpenAI 兼容上游，比如 OpenRouter。
提供 Go SDK，方便把代理能力嵌入到自己的服务里。

这类项目最有价值的地方，不是“多支持几个模型名”，而是把账号登录、协议转换和请求路由这些琐碎工作打包起来。

它适合谁用

CLIProxyAPI 更适合下面几类人：

第一类是重度 AI 编程用户。你已经在用 Codex、Claude Code、Gemini CLI，但想把它们接到 Cursor、Cline、RooCode、Amp、内部脚本或自建工作流里。

第二类是有多账号池的人。比如你有多个 Gemini、OpenAI、Claude 登录态，不想手工切换，希望自动轮询、均衡使用、遇到异常账号时能快速排查。

第三类是做团队内部网关的人。团队不希望每个客户端都分别适配 Gemini、Claude、Codex，而是想通过一个中间层统一暴露 API。

第四类是喜欢折腾协议的人。你可能关心 Responses、Chat Completions、Claude Messages、Gemini v1beta 这些接口如何互相转换，也可能希望在同一套客户端里切换不同后端。

如果只是个人偶尔问几句 AI，或者只用官方 App 聊天，那 CLIProxyAPI 的部署和维护成本就显得重了。

和普通 API 中转有什么不同

普通 API 中转服务一般是：

`1`	`客户端 -> 中转 API -> 上游模型 API`

CLIProxyAPI 的链路更像：

`1`	`客户端 -> CLIProxyAPI -> CLI / OAuth 登录态 / 多账号池 -> 模型服务`

区别在于，它处理的不只是 API Key 转发，还包括 CLI 工具、OAuth 账号、协议表面和模型别名。

比如 Codex 和 Claude Code 这类工具，本身就不是传统意义上“拿一个 API Key 就能稳定调用”的模式。CLIProxyAPI 把这些登录态和调用逻辑包装起来，让外部客户端像调用 API 一样访问它们。

这也是它吸引人的地方，同时也是它复杂的地方。

使用时最容易误解的地方

第一，不要以为统一 /v1/... 就能解决所有协议差异。

CLIProxyAPI 文档里专门提醒过：当你需要某一类后端的请求和响应形态时，优先使用 provider-specific 路径。例如 messages 风格用 /api/provider/{provider}/v1/messages，Gemini 模型路径用 /api/provider/{provider}/v1beta/models/...，chat-completions 风格用 /api/provider/{provider}/v1/chat/completions。

统一入口方便，但不同协议的语义并不会凭空消失。工具调用、流式返回、多模态输入、系统消息处理，都可能因为后端不同而有细节差异。

第二，模型名不等于唯一后端。

如果多个后端暴露了相同的客户端可见模型名，仅靠路径不一定能锁定真正执行推理的那个后端。要严格固定后端，最好使用唯一 alias、前缀，或者避免让多个后端暴露同名模型。

第三，多账号轮询不是无限额度。

轮询只能更均匀地使用账号池，不能绕过上游服务的真实限制。账号异常、配额耗尽、风控、OAuth 失效，都需要单独监控。

第四，它不是免维护魔法盒。

一旦你把它放进日常工作流，就要关心配置、日志、上游账号状态、版本升级、客户端兼容性和安全边界。

管理和监控怎么办

官方 README 提到，从 v6.10.0 开始，CLIProxyAPI 和 CPAMC 不再预置数据统计功能。如果需要使用量统计，可以配合独立项目：

CPA Usage Keeper：同步 CLIProxyAPI 数据，存到 SQLite，并提供聚合 API 和仪表盘。
CLIProxyAPI Usage Dashboard：本地优先的用量与配额看板，可展示账号、模型、时间窗口和 Codex 配额余量。
CPA-Manager：更完整的管理中心，面向请求监控、费用估算、账号池巡检、异常账号定位和清理建议。

这说明 CLIProxyAPI 的核心更偏“代理和协议层”，而不是一站式商业管理后台。如果是团队使用，最好一开始就把日志、监控和账号池管理考虑进去。

一个比较合理的使用姿势

如果要试用，可以按这个顺序来：

先用官方文档的 Quick Start 跑起来。
只接一个 provider，比如 Gemini CLI 或 Codex，确认基本请求能通。
再测试流式响应、工具调用、多模态输入这些高风险能力。
确认客户端实际使用的是哪个 endpoint，不要混用协议路径。
最后再加入多账号轮询、管理面板和用量统计。

不要一上来就把 Gemini、Codex、Claude、OpenRouter、多账号和所有客户端全接进去。这样出错时很难判断是认证问题、协议问题、模型名问题，还是上游账号问题。

安全边界也要想清楚

CLIProxyAPI 会接触到账号登录态、API Key、OAuth 相关凭据和请求内容。它如果只跑在自己机器上，风险相对可控；如果暴露到公网或团队内网，就必须认真处理认证、访问控制、日志脱敏和网络隔离。

尤其是管理端点，最好只允许本机或可信内网访问。不要为了省事直接把管理接口裸露出去。

总结

CLIProxyAPI 的价值在于，它把原本散落在多个 CLI、多个账号、多个协议里的 AI 能力，收拢成一个可编程的 API 层。

它适合重度 AI 编程用户、多账号用户和团队内部网关场景；不太适合只想“开箱即用、完全无维护”的轻量用户。

如果你正在折腾 Codex、Claude Code、Gemini CLI 这些工具，并且希望把它们接进自己的客户端或自动化工作流里，CLIProxyAPI 值得认真看一眼。但要把它当基础设施来用，而不是当一次性小工具来用。

参考资料：

让 Codex 使用 DeepSeek 模型的两种方法：本地网关和 OpenRouter BYOK

Sun, 24 May 2026 09:52:55 +0800

想让 Codex 使用 DeepSeek，第一反应通常是改 ~/.codex/config.toml：

1
2

model = "deepseek-chat"
base_url = "https://api.deepseek.com"

这个思路在一些旧版本或普通 OpenAI SDK 场景里确实成立，但放到当前 Codex CLI 上，很容易撞到一个底层问题：Codex 的自定义模型供应商走的是 OpenAI Responses 协议，而 DeepSeek 官方接口主要提供 OpenAI 兼容的 Chat Completions 调用方式。

我本机当前是 codex-cli 0.111.0。codex --help 里可以看到它支持 --config、--model、--profile 这些配置入口；OpenAI 官方 Codex 配置参考也写得很明确：model_providers.<id>.wire_api 目前只支持 responses，省略时也默认是 responses。

DeepSeek 官方文档则给出的调用路径是 https://api.deepseek.com/chat/completions，示例也是 client.chat.completions.create(...)。所以问题不在于 DeepSeek 不能被 OpenAI SDK 调用，而在于 Codex 发出去的请求语义和 DeepSeek 原生接口能理解的语义不完全是一套东西。

这就是为什么直接把 base_url 改成 https://api.deepseek.com 后，可能出现下面这些现象：

请求路径不匹配，直接 404 或返回格式不对。
多轮对话、工具调用、补丁生成时解析失败。
tool_calls 顺序、消息结构、流式事件格式对不上。
看起来模型能回一句话，但一到 Codex 真正干活就开始报错。

更稳的办法，是在 Codex 和 DeepSeek 之间放一个“翻译层”。常见有两种路线。

方法一：用本地网关桥接 DeepSeek

本地网关的作用不是简单转发，而是把 Codex 侧的 Responses 风格请求，转换成 DeepSeek 能处理的 Chat Completions 风格请求，再把 DeepSeek 的结果转换回 Codex 能吃的格式。

如果你用的是 ccx 一类本地网关，配置思路大致是这样：

[profiles.deepseek-ccx]
model = "deepseek-v4-flash"
model_provider = "ccx-bridge"

[model_providers.ccx-bridge]
name = "Local CCX Gateway"
base_url = "http://localhost:3000/v1"
env_key = "DEEPSEEK_API_KEY"

然后在终端里设置 DeepSeek Key，再用这个 profile 启动：

1
2

export DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

PowerShell 里是：

1
2

$env:DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

这里有两个细节要注意。

第一，base_url 要指向网关暴露给 Codex 的地址，不是 DeepSeek 官方地址。网关背后再去调用 DeepSeek。

第二，env_key 写什么取决于网关怎么鉴权。有的网关直接读取 DeepSeek 官方 Key，有的网关会要求你给它一个本地代理 Key，再由网关自己的后台保存 DeepSeek Key。遇到这种情况，env_key 就应该改成网关要求的环境变量名。

这条路的优点是本地可控，延迟和成本也更容易算清楚。缺点是你必须确认网关真的支持 Codex 当前使用的 Responses 语义，而不是只做了普通 Chat Completions 代理。

方法二：用 OpenRouter BYOK 做线上桥接

如果不想在本地部署网关，可以考虑 OpenRouter 的 BYOK。BYOK 的意思是把你自己的上游供应商 Key 绑定到 OpenRouter，由 OpenRouter 负责路由和转发。

这里最容易写错的是环境变量。Codex 访问的是 OpenRouter，所以 env_key 通常应该是 OPENROUTER_API_KEY，不是 DEEPSEEK_API_KEY。DeepSeek Key 要在 OpenRouter 的 BYOK 或 provider key 设置里添加。

配置示例：

[profiles.deepseek-openrouter]
model = "deepseek/deepseek-chat"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

启动方式：

1
2

export OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

PowerShell：

1
2

$env:OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

然后在 OpenRouter 后台把 DeepSeek 的 provider key 加进去。OpenRouter 的 BYOK 文档说明，绑定的 provider key 会被加密保存，并用于路由到对应供应商。

这条路的优点是省掉本地网关维护成本，配置起来更像普通第三方 API 代理。缺点是中间多了一层线上服务，排障时要同时看 Codex、OpenRouter、DeepSeek 三边的错误信息。

要不要继续用 deepseek-chat 这个模型名？

DeepSeek 官方文档在 2026 年 5 月的说明里，推荐模型名已经出现 deepseek-v4-flash 和 deepseek-v4-pro，并提示 deepseek-chat、deepseek-reasoner 兼容别名会在 2026-07-24 之后废弃。

所以新配置里更建议优先测试：

`1`	`model = "deepseek-v4-flash"`

如果走 OpenRouter，则要按 OpenRouter 的模型命名来写，例如：

`1`	`model = "deepseek/deepseek-chat"`

实际可用名称以你所用网关或 OpenRouter 模型页为准。模型名不对时，错误通常会表现为 model not found、404，或者 provider 找不到对应 endpoint。

直接改 DeepSeek 官方 base_url 为什么不推荐

你当然可以试着写：

[profiles.deepseek-direct]
model = "deepseek-v4-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

但这更像排错实验，不适合作为稳定方案。因为 Codex 会按 Responses 协议去和自定义 provider 说话，而 DeepSeek 官方示例走的是 /chat/completions。如果 DeepSeek 或 Codex 未来补齐了兼容层，这种直连才可能变得简单；在此之前，桥接层更靠谱。

改完配置后还是走 OpenAI 怎么办

先确认配置文件位置。全局配置应该在：

`1`	`~/.codex/config.toml`

项目里的 .codex/config.toml 不适合放 model_provider、model_providers 这类机器级 provider 配置。OpenAI 官方文档也提醒，项目级配置不会覆盖这些本地 provider 和认证相关字段。

如果 Codex 仍然要求网页登录，或者看起来还在走默认 OpenAI 模型，可以先退出当前登录态：

`1`	`codex logout`

有些旧教程会写成交互界面里的 /logout。在当前 CLI 里，更稳的是直接在终端执行 codex logout。

还可以用临时参数做一次快速验证：

`1`	`codex --profile deepseek-ccx`

或者：

`1`	`codex -c model_provider=ccx-bridge -c model=deepseek-v4-flash`

如果这样能生效，说明配置本身可读；如果不生效，优先检查 profile 名称、TOML 语法、环境变量是否只在当前 shell 里有效。

排障清单

401：Key 不对，或者 env_key 指向了错误的环境变量。
404：base_url 或模型名不对，也可能是把 Responses 请求打到了只支持 Chat Completions 的地址。
tool_calls、patch、流式解析报错：大概率是协议桥接不完整。
仍然提示登录 OpenAI：执行 codex logout，再确认是否用了正确 profile。
PowerShell 设置环境变量后新开窗口失效：$env:... 只对当前会话生效，需要长期保存就改用户环境变量。
OpenRouter BYOK 没走自己的 DeepSeek Key：检查 OpenRouter 后台 provider key 是否绑定、是否允许当前 OpenRouter API Key 使用，以及是否开启了 fallback。

结论

让 Codex 使用 DeepSeek，不是不能改 config.toml，而是不能只改 base_url 就指望一切自动兼容。

当前更稳的两条路是：

用本地网关做协议桥接，Codex 连本地网关，网关再连 DeepSeek。
用 OpenRouter BYOK 做线上转发，Codex 连 OpenRouter，DeepSeek Key 绑定在 OpenRouter 后台。

如果只是想快速试用，OpenRouter 路线更省事；如果你希望 Key、成本、日志都尽量掌握在自己手里，本地网关更适合长期折腾。

参考资料：

CodeGraph 是什么？给 Claude Code、Codex 和 Cursor 加一个本地代码地图

Sat, 23 May 2026 21:09:46 +0800

CodeGraph 是一个给 AI 编程工具使用的本地代码知识图谱。它会提前给项目建立索引，把符号关系、调用图、代码结构、路由关系等信息整理成可查询的图，让 Claude Code、Codex CLI、Cursor、OpenCode、Hermes Agent 这类工具不用每次都靠 grep、glob、Read 和子代理到处翻文件。

它解决的是一个很实际的问题：AI Agent 看大型代码库时，很多成本不是花在真正修改代码上，而是花在“找代码在哪里”。如果每次都重新搜索、读取、筛选，token、时间和工具调用都会被消耗掉。CodeGraph 的思路是先把代码库变成一张本地地图，让 Agent 先问地图，再决定要不要读具体文件。

它主要解决什么痛点

AI 编程工具在小项目里通常还好，文件少，搜索快，读一遍也不贵。但项目一大，常见问题就会出现：

Agent 为了理解一个模块，反复调用 grep、find、ls、Read。
探索子代理读了很多无关文件，主任务上下文却没有变清楚。
问一个架构问题时，token 大量花在定位文件上。
改一个函数前，不知道谁在调用它、它又调用了谁。
Web 项目里，URL 路由和实际处理函数之间的关系不够直观。

CodeGraph 试图把这些“先找路”的工作前置。项目索引建好后，Agent 可以直接查询相关符号、调用方、被调用方、影响范围和代码片段。

安装方式

项目提供跨平台安装脚本，不要求用户自己准备 Node.js：

`1`	`curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh \| sh`

Windows PowerShell 可以使用：

`1`	`irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 \| iex`

如果已经有 Node 环境，也可以直接用 npm：

`1`	`npx @colbymchenry/codegraph`

或者全局安装：

`1`	`npm i -g @colbymchenry/codegraph`

安装器会自动检测并配置已安装的 Agent，例如 Claude Code、Cursor、Codex CLI、opencode 和 Hermes Agent。它会写入对应的 MCP server 配置和指令文件，让这些工具知道什么时候调用 CodeGraph。

初始化项目

安装完成后，需要在目标项目里建立索引：

1
2

cd your-project
codegraph init -i

这个命令会生成项目级知识图谱索引。README 中提到，只要项目里存在 .codegraph/ 目录，Agent 就可以自动使用 CodeGraph 工具。

如果不想继续使用，也可以卸载全局配置：

`1`	`codegraph uninstall`

它会移除安装器写入的 MCP server 配置、指令和权限。项目中的 .codegraph/ 索引不会被自动删除，如果要移除项目索引，需要使用 codegraph uninit。

为什么它对 Agent 有用

Claude Code、Codex CLI、Cursor 这类工具在理解代码库时，常常会先做探索：找文件、读入口、查引用、再追调用链。这个过程对人来说像“翻项目”，对模型来说就是一串工具调用和上下文消耗。

CodeGraph 把这一步变成索引查询。Agent 可以先用 codegraph_context 找到相关入口、符号和片段，再用 codegraph_explore 或其他工具读取必要内容。这样做的好处是：

少读无关文件。
少调用搜索工具。
更快找到真正相关的代码。
改动前更容易看清影响范围。
大型仓库里的架构问题更容易回答。

项目 README 给出的基准测试显示，在 7 个真实开源代码库上，对比启用 CodeGraph 和不启用 CodeGraph，平均结果是成本更低、token 更少、速度更快、工具调用更少。具体数字会受项目规模、语言、问题类型和 Agent 使用方式影响，但方向很清楚：越大的仓库，预索引的价值越明显。

核心能力

1. 智能上下文构建

一个工具调用可以返回入口点、相关符号和代码片段，减少 Agent 先派一堆探索任务再慢慢筛选的情况。对架构理解、模块定位、功能入口分析很有用。

2. 全文搜索

CodeGraph 使用 FTS5 做全文搜索，可以在整个代码库里快速按名称和文本查找代码。这不是替代所有 grep 场景，而是让 Agent 有一个更结构化的第一站。

3. 影响分析

在改函数、类、方法或路由前，可以查询 callers、callees 和影响半径。对重构、修 bug、删除旧代码尤其有用，因为最怕的就是只改了当前文件，却漏掉上游或下游调用。

4. 自动保持新鲜

README 中提到，CodeGraph 使用原生文件系统事件，例如 FSEvents、inotify、ReadDirectoryChangesW，并带有 debounce auto-sync。意思是索引会随着本地代码变化自动更新，不需要每改一个文件都手动重建。

5. 多语言支持

项目列出的支持范围超过 19 种语言，包括 TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal / Delphi 等。

这让它更适合多语言仓库和全栈项目，而不是只服务某一种语言。

6. Web 路由感知

CodeGraph 还会识别多种 Web 框架里的路由文件和路由声明，把 URL pattern 和处理函数连接起来。README 中提到的框架包括 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor、React Router、SvelteKit 等。

这点很实用。很多 Web 项目的真实入口不是某个明显的 main 函数，而是路由、controller、handler、view 或 resolver。Agent 如果能先知道 URL 到处理函数的关系，理解业务流程会快很多。

本地优先的设计

CodeGraph 强调 100% local。它不需要 API key，不依赖外部服务，索引数据保存在本地 SQLite 数据库里。

对企业项目、私有仓库或敏感代码来说，这个设计很重要。AI 工具接入代码库时，大家最担心的往往不是“能不能查到代码”，而是“代码结构和索引会不会被发出去”。CodeGraph 的定位是本地构建、本地查询、本地服务 Agent。

当然，本地也意味着要考虑磁盘空间、索引时间、文件监听和项目规模。如果仓库特别大，第一次初始化和后续同步仍然需要资源。

适合哪些场景

CodeGraph 更适合这些场景：

大型代码库，经常需要问架构和调用链问题。
使用 Claude Code、Codex CLI、Cursor 等 Agent 做代码理解和修改。
希望减少 Agent 到处读文件、乱搜、反复探索。
需要在改动前分析影响范围。
Web 项目路由复杂，需要快速从 URL 找到处理函数。
团队希望给 AI Agent 一个更稳定的本地项目索引。

如果只是几十个文件的小项目，普通搜索已经够快，CodeGraph 的优势可能不明显。它最有价值的地方，是中大型代码库和经常让 Agent 做探索的场景。

使用时要注意什么

第一，CodeGraph 不是替代代码审查和测试的工具。它能帮助 Agent 更快找到相关代码，但不能保证 Agent 的修改一定正确。

第二，索引质量会影响使用效果。项目结构复杂、生成代码很多、语言混杂或 build 产物没有排除时，索引可能会变得臃肿。使用前最好确认 .gitignore、项目目录和索引范围是否合理。

第三，MCP 配置和 Agent 指令很关键。README 里也提醒，CodeGraph 只有在被正确查询时才有帮助。如果 Agent 仍然绕开它去大量读文件，预索引就会变成额外开销。

第四，虽然它是本地工具，也要注意权限。安装器会写入 Agent 配置和权限列表，团队环境中最好统一审查这些配置。

小结

CodeGraph 的价值可以简单理解为：给 AI Agent 一张本地代码地图。它不是让模型更聪明，而是让模型少迷路。

当 Claude Code、Codex CLI、Cursor 这类工具面对大型仓库时，最耗费上下文的往往是探索过程。CodeGraph 用预索引的符号关系、调用图、路由图和全文搜索，把“找代码”这一步提前做好，让 Agent 把更多预算花在理解和修改上。

如果你已经在真实项目里使用 AI 编程工具，并且经常遇到“它读了一堆文件还是没找到重点”的情况，CodeGraph 值得试一下。它代表了 AI 编程工具的一个重要方向：不只是换更强的模型，也要给模型更好的本地代码上下文。

参考资料：

GitHub 项目：https://github.com/colbymchenry/codegraph

oh-my-pi 是什么？一个把终端、IDE 和调试器打通的 AI 编程助手

Sat, 23 May 2026 19:02:20 +0800

oh-my-pi 是一个面向终端和编辑器的 AI Coding Agent。它来自 Mario Zechner 的 Pi 项目分支，由 can1357 继续扩展，目标不是只做一个命令行聊天界面，而是把文件读取、代码搜索、结构化编辑、LSP、调试器、浏览器、子代理和多模型提供商接到同一个编程工作流里。

从项目 README 看，它更像一套 AI 编程工具底座：终端里可以直接交互，编辑器可以通过 ACP 接入，Node 项目也可以通过 SDK 嵌入。对已经在用 Claude Code、Codex CLI、Cline、Cursor 或其他 Agent 工具的人来说，oh-my-pi 值得关注的地方在于它把很多原本分散在外部工具里的能力做成了内置工具面。

它主要解决什么问题

很多 AI 编程工具的短板不在模型本身，而在工具接口。模型想改代码时，如果只能拿到粗糙的全文、脆弱的字符串替换和一次性 shell，失败率就会被工具链放大。

oh-my-pi 的思路是把这些常见摩擦点压低：

读取文件时优先给结构化摘要，而不是把整份文件塞进上下文。
搜索、glob、find、语法高亮、token 计数等能力尽量放进原生实现，减少对外部命令的依赖。
写代码时接入 LSP，让重命名、引用查找、文件移动更接近 IDE 行为。
调试时接入 lldb、dlv、debugpy 等 DAP 工具，而不是只靠日志和猜测。
复杂任务可以拆给子代理，并用结构化结果返回。
对编辑操作使用内容锚点和预览机制，降低错误 patch 直接落盘的概率。

这些设计说明它关注的不是“模型会不会回答”，而是“模型能不能稳定完成一次真实代码修改”。

安装方式

项目提供了几种安装入口。macOS 和 Linux 可以使用安装脚本：

`1`	`curl -fsSL https://omp.sh/install \| sh`

如果使用 Bun，官方推荐全局安装 npm 包：

`1`	`bun install -g @oh-my-pi/pi-coding-agent`

Windows PowerShell 可以使用：

`1`	`irm https://omp.sh/install.ps1 \| iex`

项目 README 还提到可以通过 mise 固定版本：

`1`	`mise use -g github:can1357/oh-my-pi`

安装前要注意 Bun 版本要求。README 中标注的平台范围包括 macOS、Linux、Windows，并要求 bun >= 1.3.14。

值得关注的能力

1. 工具调用不只停留在 shell

oh-my-pi 内置了文件读取、搜索、写入、编辑、AST 编辑、浏览器、任务拆分、调试、LSP 等工具。README 中提到它有 32 个内置工具、13 个 LSP 操作和 27 个 DAP 操作。

这意味着 Agent 不必把所有事情都包装成命令行输出。比如查引用可以走 LSP，读 PR 或 issue 可以走统一的文件式接口，网页和 PDF 可以被转换成带链接结构的 Markdown，再交给模型处理。

2. LSP 接入更适合真实代码库

对大型项目来说，重命名和移动文件最怕漏掉 re-export、别名导入、barrel file 或跨目录引用。oh-my-pi 的 README 特别强调写入路径会接入 LSP，例如文件重命名会经过 workspace/willRenameFiles，让编辑更接近 IDE 的语义操作。

这类能力适合 TypeScript、Rust、Go、Python 等项目里的日常重构，尤其是那些“手动改能改，但很容易漏一个引用”的场景。

3. 调试器是一级工具

很多 AI 编程流程遇到崩溃时，仍然停留在添加日志、重新运行、再读输出。oh-my-pi 把 DAP 调试器接入工具面，README 里举了 C 程序用 lldb、Go 服务用 dlv、Python 进程用 debugpy 的例子。

这会改变 Agent 处理 bug 的方式：它可以暂停进程、查看栈帧、读局部变量，再决定下一步，而不是只靠报错文本猜测。

4. Hashline 编辑降低 patch 失败率

项目强调的 Hashline 是一种基于内容锚点的编辑方式。它的目标是让模型指向要修改的内容锚点，而不是反复输出大段 diff。这样做的好处是减少空格、上下文过期、字符串匹配失败造成的编辑错误。

对 Agent 工具来说，这类机制很重要。模型能力再强，如果写入接口经常失败，最终体验仍然会变成反复重试。

5. 子代理和工作区隔离

README 中介绍了 task 子代理能力：一个任务可以拆给多个隔离 worker，结果再以结构化对象返回。项目还包含工作区隔离相关实现，用来支持并行任务、分支探索和避免互相覆盖。

这适合代码审查、迁移、批量修复、测试定位等任务。真正的价值不只是“并行更快”，而是让不同探索路径之间的上下文和文件改动更清楚。

6. 兼容已有规则和配置

oh-my-pi 首次运行时会读取已有工具留下的规则和配置，包括 .claude、.cursor、.windsurf、.gemini、.codex、.cline、.github/copilot 和 .vscode 等目录。

这点很实用。很多团队已经为不同 AI 工具写过规则，如果每换一个工具都要迁移一遍，成本会很高。oh-my-pi 的做法是尽量直接继承已有上下文。

四种入口

项目提供了四类使用入口：

交互式 TUI：在终端里直接运行 omp。
一次性命令：用 omp -p 发送单次 prompt。
Node SDK：通过 @oh-my-pi/pi-coding-agent 嵌入到 Node 或 TypeScript 项目。
RPC / ACP：通过 stdio 或 Agent Client Protocol 接入其他程序和编辑器。

这说明它不只面向个人终端用户，也给 IDE、插件、自动化平台和内部工具留了集成空间。

适合谁尝试

oh-my-pi 比较适合这几类用户：

经常在终端里做代码修改、调试和审查的人。
已经在使用 AI Coding Agent，但觉得文件读取、patch、搜索或调试链路不够稳的人。
想把 Agent 接入编辑器、RPC 或 Node 服务的开发者。
需要在一个工具里切换多模型和多提供商的人。
对 LSP、DAP、AST 编辑和子代理这些底层能力感兴趣的工具开发者。

如果只是想要一个开箱即用的聊天式代码助手，学习成本可能会偏高。它更适合愿意理解工具链，并把 Agent 当成可配置开发环境的人。

使用时要注意什么

第一，oh-my-pi 仍然是快速演进中的开源项目。仓库提交频繁，issue 和 PR 数量也不少，安装和使用时要预期到变化。

第二，它的能力边界和本地环境强相关。LSP、调试器、Bun、模型提供商认证、终端环境、Windows 或 Unix 差异都会影响体验。

第三，内置工具多不等于每个场景都应该全开。实际使用时更适合按任务启用需要的工具，把规则、权限和工作区边界配置清楚。

第四，AI Agent 能写代码，也能误改代码。即使有预览和锚点编辑机制，重要项目仍然要保留版本控制、测试和人工审查。

小结

oh-my-pi 的亮点不在于又做了一个 AI 终端壳，而在于它把 AI 编程中最容易拖后腿的工具层重新整理了一遍：文件读取、搜索、编辑、LSP、调试、浏览器、子代理和 SDK 都被放进同一个 Agent 工作流。

它适合关注 AI 编程基础设施的人，也适合想比较不同 Coding Agent 路线的开发者。当前 AI 编程工具的竞争，已经不只是模型回答质量的竞争，也是在比谁能把模型稳定接入真实代码库、真实调试流程和真实团队规则。oh-my-pi 正是在这个方向上给出了一套很激进的开源实现。

参考资料：

GitHub 项目：https://github.com/can1357/oh-my-pi
官方站点：https://omp.sh/
SDK 文档：https://omp.sh/docs/sdk

Graphify 解决 Claude Code 最大局限：把代码库变成 AI 可查询知识图谱

Thu, 21 May 2026 08:02:32 +0800

safishamsi/graphify 是一个面向 AI 编程助手的知识图谱工具。它的目标很直接：把一个项目目录里的代码、文档、SQL schema、脚本、论文、图片、视频和音频，整理成可查询的知识图谱，让 AI 助手不再只靠 grep、全文阅读或临时搜索来理解项目。

项目地址：safishamsi/graphify

截至本文整理时，GitHub 页面显示项目约有 50.2k stars、5.4k forks，许可证为 MIT。README 对它的描述是：在 AI 编程助手里输入 /graphify，它就会把整个项目映射成一个可以查询的知识图谱。

它解决的核心问题

AI 编程助手越来越强，但在真实代码库里仍然经常遇到几个问题：

不知道关键模块之间怎么连接。
读了很多文件，但没形成整体架构地图。
搜索命中了文本，却不知道上下游依赖。
代码、数据库 schema、文档和基础设施配置分散在不同地方。
多人协作时，每个人对项目结构的理解不一致。

Graphify 想做的是给项目生成一层“记忆层”。它把代码实体、文档概念、数据库表、配置、设计说明和跨文件关系连接起来，让 AI 助手可以按图谱查询，而不是每次从零开始扫文件。

最小使用方式

Graphify 的最小用法非常简单。安装后，在 AI 编程助手里输入：

`1`	`/graphify .`

在 PowerShell 里要注意，前导 / 会被当成路径分隔符，所以 Windows PowerShell 下应使用：

`1`	`graphify .`

运行后会生成 graphify-out/ 目录，核心文件包括：

graphify-out/
├── graph.html
├── GRAPH_REPORT.md
└── graph.json

这三个文件分工不同：

graph.html：浏览器里打开的交互式图谱，可以点击节点、过滤和搜索。
GRAPH_REPORT.md：项目亮点、关键概念、意外连接和推荐问题。
graph.json：完整图谱，后续可以直接查询，不必重新读所有文件。

如果想生成更可读的架构页面和 Mermaid 调用流图，可以运行：

`1`	`graphify export callflow-html`

安装和平台支持

Graphify 的 PyPI 包名是 graphifyy，注意是双 y。README 特别提醒，PyPI 上其他 graphify* 包并不属于该项目，但 CLI 命令仍然叫 graphify。

推荐安装方式是：

`1`	`uv tool install graphifyy`

也可以使用：

1
2

pipx install graphifyy
pip install graphifyy

安装后注册到 AI 助手：

`1`	`graphify install`

项目支持的平台很多，包括 Claude Code、Codex、OpenCode、GitHub Copilot CLI、VS Code Copilot Chat、Aider、Cursor、Gemini CLI、Kimi Code、Kiro、Google Antigravity 等。不同平台可以用不同安装命令，例如：

graphify install --platform codex
graphify install --platform gemini
graphify cursor install
graphify antigravity install

Codex 用户还需要在 ~/.codex/config.toml 的 [features] 下加入：

`1`	`multi_agent = true`

README 也说明，Codex 使用 $graphify，不是 /graphify。

它能处理哪些文件

Graphify 覆盖的输入类型很广。

代码方面，它支持 31 种语言，包括 Python、TypeScript、JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、SQL、Shell、JSON 等。

文档方面，它支持：

.md
.mdx
.qmd
.html
.txt
.rst
.yaml
.yml

还可以通过可选依赖扩展更多类型：

pip install "graphifyy[pdf]"
pip install "graphifyy[office]"
pip install "graphifyy[video]"
pip install "graphifyy[mcp]"
pip install "graphifyy[neo4j]"
pip install "graphifyy[sql]"
pip install "graphifyy[all]"

其中，pdf 用于 PDF 提取，office 用于 .docx 和 .xlsx，video 用于视频和音频转写，mcp 用于 MCP stdio server，neo4j 用于推送到 Neo4j，sql 用于 SQL schema 提取。

生成的报告有什么价值

GRAPH_REPORT.md 不是普通摘要，它会把项目里更值得 AI 助手关注的关系挑出来。

README 里提到的报告内容包括：

God nodes：项目里连接最多的核心概念。
Surprising connections：跨文件、跨模块的意外连接。
The why：从注释、docstring、设计文档里提取出的设计理由。
Suggested questions：图谱特别适合回答的问题。
Confidence tags：关系会标记为 EXTRACTED、INFERRED 或 AMBIGUOUS。

这点很关键。普通搜索只能告诉你“哪里出现了这个词”，而图谱可以回答“这个概念和哪些模块、配置、表、文档有关”。对大型代码库来说，这比单纯全文检索更接近架构理解。

常用命令

Graphify 的常见命令包括：

/graphify .
/graphify ./docs --update
/graphify . --cluster-only
/graphify . --no-viz
/graphify . --wiki
graphify export callflow-html
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

也可以把论文或视频加入图谱：

1
2

/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>

如果要做 PR 辅助分析，还可以使用：

graphify prs
graphify prs 42
graphify prs --triage
graphify prs --conflicts

这类命令适合代码评审场景：看 PR 影响了哪些图谱社区、是否和其他 PR 有冲突风险、哪些 review queue 更值得优先处理。

和 MCP、Neo4j、CI 的关系

Graphify 不只是生成 HTML 图。它也可以把图谱暴露给 AI 助手反复调用。

例如可以启动 MCP server：

`1`	`python -m graphify.serve graphify-out/graph.json`

MCP server 提供的能力包括 query_graph、get_node、get_neighbors、shortest_path、list_prs、get_pr_impact、triage_prs 等。

它也支持 Neo4j 导出或推送：

1
2

/graphify ./raw --neo4j
/graphify ./raw --neo4j-push bolt://localhost:7687

团队协作上，README 建议可以提交 graphify-out/，让团队每个人拉取后都能共享同一份项目地图。还可以运行：

`1`	`graphify hook install`

这样每次 git commit 后自动重建图谱，并设置 merge driver，避免 graph.json 在多人并行提交时留下冲突标记。

隐私和成本要怎么看

Graphify 的 README 对隐私边界写得比较清楚。

代码文件会通过 tree-sitter 在本地解析，不会发出 API 调用。视频和音频可以通过 faster-whisper 本地转写。文档、PDF、图片这类语义提取内容，则会通过你的 AI 助手模型 API 处理。

如果用 headless graphify extract，可能需要设置这些环境变量：

ANTHROPIC_API_KEY
GEMINI_API_KEY
GOOGLE_API_KEY
OPENAI_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
OLLAMA_BASE_URL

本地 Ollama、AWS Bedrock、Claude Code CLI 等也可以作为 backend。README 还写明项目没有 telemetry、usage tracking 和 analytics。

实际使用时要注意：代码本地解析不等于所有内容都不出网。涉及文档、PDF、图片或云端模型时，仍然要看 backend、API key、企业合规和数据边界。

适合哪些场景

Graphify 适合几类用户：

想让 Claude Code、Codex、Cursor、Gemini CLI 更懂项目结构的开发者。
需要快速理解大型陌生代码库的人。
需要把代码、SQL schema、文档、配置放在一起分析的团队。
做架构审查、PR review、重构影响分析的人。
希望把项目知识暴露成 MCP 工具给 Agent 使用的人。
想为团队保留“项目地图”的技术负责人。

它不一定适合所有项目。小型脚本、一次性 demo、结构非常简单的仓库，用普通搜索和 README 可能已经够用。Graphify 的价值更容易出现在模块多、文档多、团队协作多、AI 助手频繁参与开发的大项目里。

小结

Graphify 的意义在于，它把 AI 编程助手的上下文从“临时读取文件”推进到“长期可查询的项目知识图谱”。

对开发者来说，它不是替代 IDE、搜索或 LSP，而是给 AI 助手补一层结构化记忆：哪些模块重要、哪些概念连接紧密、哪些文档解释了设计理由、某个 PR 会影响哪些社区。随着 Codex、Claude Code、Gemini CLI、Antigravity 这类 Agent 工具继续普及，这类“项目图谱层”会越来越有用。

参考来源：

GitHub：safishamsi/graphify

Vercel AI SDK 是什么？TypeScript 开发者构建 AI 应用的统一工具包

Sun, 17 May 2026 23:07:38 +0800

vercel/ai 是 Vercel 维护的开源 AI SDK。

它的定位很明确：给 TypeScript 开发者提供一套统一工具，用来构建 AI 应用和 AI Agent。它来自 Next.js 背后的团队，但并不只服务于 Next.js，也支持 React、Svelte、Vue、Angular 等 UI 框架，以及 Node.js 等运行时。

项目地址：https://github.com/vercel/ai

如果你正在做聊天应用、AI 写作工具、RAG 应用、带工具调用的 Agent、流式输出界面，或者想把多个模型供应商接到同一个应用里，Vercel AI SDK 是一个值得关注的基础库。

它解决的核心问题

现在做 AI 应用，最大麻烦之一不是“能不能调模型”，而是不同模型供应商的接口、流式输出、工具调用、错误处理和前端状态管理都不一样。

例如：

OpenAI 有自己的 SDK 和响应格式。
Anthropic 有自己的消息结构。
Google、xAI、Mistral、DeepSeek、Groq 等也各有差异。
流式输出需要处理 chunk。
工具调用需要处理模型发起的结构化请求。
前端聊天 UI 还要管理消息、加载状态、取消、重试和错误展示。

如果每个供应商都手写一套适配层，项目会很快变复杂。

Vercel AI SDK 的思路是把这些差异收敛到统一 API 后面。开发者用一套接口写应用，再通过 Provider 接入不同模型。

统一 Provider 架构

Vercel AI SDK 的一个核心特点，是 provider-agnostic，也就是不绑定单一模型厂商。

它可以通过统一 API 访问 OpenAI、Anthropic、Google 等模型提供方。项目 README 还提到，默认情况下 AI SDK 会使用 Vercel AI Gateway，让开发者更容易访问多个主流 provider。

这对工程项目很实用。

因为很多 AI 产品最终都不会只依赖一个模型：

有的任务适合强推理模型。
有的任务适合便宜快速模型。
有的任务需要多模态。
有的任务需要长上下文。
有的任务需要本地或私有部署模型。

统一 Provider 架构让应用更容易做模型切换、灰度测试、成本控制和备选方案。

流式输出是前端体验的关键

AI 应用和传统 API 最大的体验差异之一，是响应可能很长。

如果用户每次都要等完整回答返回，聊天工具、写作工具和代码助手会显得很慢。流式输出可以让文本逐步显示，用户更早看到结果。

Vercel AI SDK 对流式生成做了比较完整的封装。开发者不需要从零处理底层事件流，而是可以使用 SDK 提供的生成和流式接口，把模型输出接到前端 UI。

这对 Next.js / React 应用尤其方便。

一个 AI 聊天界面看起来简单，但实际要处理：

消息列表。
用户输入。
服务器请求。
流式 token 展示。
加载状态。
错误状态。
中止生成。
重新生成。

这些都是 AI SDK 试图帮开发者减少重复劳动的地方。

工具调用和 Agent 场景

随着 AI 应用从“聊天”走向“做事”，工具调用变得越来越重要。

模型不只是输出自然语言，还可能需要调用外部函数：

查数据库。
搜索文档。
调用业务 API。
读取订单状态。
生成图表。
创建日历事件。
修改项目文件。

Vercel AI SDK 支持工具调用相关能力，让开发者可以定义工具、参数和执行逻辑，再让模型在合适时机请求调用。

这也是它从“聊天 UI SDK”扩展到“AI 应用和 Agent 工具包”的关键。

不过，工具调用不是加上去就万事大吉。真实项目还要考虑：

参数校验。
权限边界。
工具调用日志。
幂等性。
超时和重试。
人工确认。
敏感操作限制。

AI SDK 可以帮助处理接口和流程，但安全边界仍然需要开发者自己设计。

UI 集成能力

Vercel AI SDK 对前端框架比较友好。

它不仅提供核心生成 API，也围绕聊天、补全、消息状态和流式 UI 做了封装。对于使用 Next.js 和 React 的团队来说，这能减少很多样板代码。

但它并不只适合 Vercel 部署。

如果你的项目本身是 TypeScript 技术栈，或者后端运行在 Node.js 环境，AI SDK 仍然可以作为模型调用和流式处理层来使用。是否部署在 Vercel，取决于你的应用架构、团队习惯和基础设施选择。

Skill for Coding Agents

vercel/ai README 里还有一个有趣的建议：如果你使用 Claude Code、Cursor 等 coding agent，可以把 AI SDK skill 加到仓库里。

示例命令是：

`1`	`npx skills add vercel/ai`

这说明 Vercel 已经意识到，AI SDK 的用户不只是人类开发者，也包括 coding agent。

当 agent 修改使用 AI SDK 的项目时，如果仓库里有专门的 skill，它可以更好地理解 SDK 约定、常见 API、项目结构和最佳实践，减少乱写代码的概率。

这个方向很值得注意。

未来开源项目可能不只提供 README 和 docs，还会提供给 AI coding agent 使用的结构化技能说明。对复杂 SDK 来说，这会变成新的开发者体验入口。

适合哪些项目

Vercel AI SDK 适合这几类场景：

基于 Next.js / React 的 AI 聊天应用。
需要流式输出的写作、问答、客服和代码助手。
需要接入多个模型 provider 的 AI 产品。
想快速构建 RAG 或文档问答原型的团队。
需要工具调用、函数调用或轻量 Agent 能力的应用。
已经使用 TypeScript / Node.js 技术栈的团队。

它尤其适合前端和全栈开发者。因为很多 AI 应用的难点不只是模型调用，而是如何把模型输出变成稳定、流畅、可交互的产品体验。

不适合什么场景

如果你的项目主要是 Python 后端、深度学习训练、模型微调或底层推理服务，Vercel AI SDK 可能不是核心工具。

它更偏应用层，而不是模型训练框架。

如果你需要的是：

自己训练模型。
管理 GPU 推理集群。
做底层 batch inference。
深度控制 tokenizer、KV cache、量化和推理引擎。

那更应该看 PyTorch、vLLM、SGLang、TensorRT-LLM、llama.cpp 或云厂商推理服务。

Vercel AI SDK 更像“把模型能力接进产品”的应用开发层。

使用时要注意什么

第一，不要把统一 API 理解成完全无差异。

不同模型 provider 的能力、上下文长度、工具调用格式、流式细节、错误类型和计费方式仍然不同。统一 SDK 能减少工程摩擦，但不能消除模型差异。

第二，要控制成本。

AI 应用一旦上线，流式聊天、重试、工具调用、RAG 检索和多模型 fallback 都可能增加调用成本。需要做限流、缓存、日志和预算监控。

第三，要处理安全边界。

如果模型能调用工具，就必须限制工具能做什么。不要让模型直接执行高风险操作，也不要把密钥、数据库写权限和生产环境操作裸露给模型。

第四，要保留可观测性。

AI 应用出问题时，不能只看前端报错。你需要知道用户输入、模型选择、工具调用、响应时间、token 消耗、错误类型和最终输出。

小结

vercel/ai 不是一个新的模型，也不是单纯的聊天组件。

它更像 TypeScript AI 应用开发的基础设施：统一 Provider、流式输出、工具调用、前端状态管理和 agent 场景，都被放进一个开源 SDK 里。

对已经使用 Next.js、React、TypeScript、Node.js 的团队来说，它可以显著降低从“模型 API 能跑”到“产品体验可用”的工程成本。

但它也不是万能层。模型选择、权限设计、成本控制、日志监控和业务安全，仍然需要开发者自己负责。

如果你想做 AI 应用，而不是训练模型，Vercel AI SDK 是一个值得先试的工具包。

参考资料

Bun：把 JavaScript 运行时、包管理器、测试和打包合在一起

Sun, 17 May 2026 17:42:25 +0800

Bun 是 oven-sh 开源的 JavaScript / TypeScript 一体化工具链。

它不是只想做一个更快的 Node.js 替代品，而是把运行时、包管理器、脚本运行器、测试运行器和打包器都塞进同一个 bun 命令里。对前端和 Node.js 开发者来说，Bun 的吸引力在于：少装一堆工具，少等一堆安装和构建过程，很多常见任务可以直接用一个命令完成。

项目地址：https://github.com/oven-sh/bun

先说结论

Bun 最适合想简化 JavaScript 工具链的人。

它能做这些事：

运行 JavaScript、TypeScript、JSX 和 TSX。
作为 Node.js 兼容运行时。
替代 npm / yarn / pnpm 做包管理。
运行 package.json 里的 scripts。
执行测试。
打包前端或后端代码。
用 bunx 执行 npm 包里的命令。
提供 Bun.serve、bun:sqlite、Bun.sql、Bun.redis、Bun.s3 等内建 API。

它最明显的价值是开发体验：安装依赖快、启动快、命令统一、TypeScript 和 JSX 开箱即用。

但 Bun 也不是所有项目都该立刻切换。大型 Node.js 项目、依赖大量原生扩展的项目、生产稳定性要求极高的服务，仍然需要逐项验证兼容性、构建行为、测试行为和部署方式。

Bun 是什么

按照官方 README 的描述，Bun 是一个面向 JavaScript 和 TypeScript 应用的一体化工具包。它以单个可执行文件 bun 发布。

它的核心是 Bun runtime：一个快速 JavaScript 运行时，目标是作为 Node.js 的 drop-in replacement。Bun 使用 Zig 编写，底层基于 JavaScriptCore，重点优化启动时间和内存占用。

这意味着你可以直接运行：

`1`	`bun run index.tsx`

TypeScript 和 JSX 不需要额外配置就能跑。

同一个 bun 命令还包含：

test runner
script runner
Node.js 兼容包管理器
bundler
package runner

常见命令包括：

bun test
bun run start
bun install <pkg>
bunx cowsay 'Hello, world!'

过去一个项目里可能同时出现 node、npm、pnpm、tsx、jest、vitest、webpack、esbuild、ts-node 等工具。Bun 的路线是尽量把高频路径收进一个工具里。

安装方式

Bun 支持 Linux、macOS 和 Windows，覆盖 x64 与 arm64。

官方推荐安装脚本：

`1`	`curl -fsSL https://bun.com/install \| bash`

Windows：

`1`	`powershell -c "irm bun.sh/install.ps1 \| iex"`

也可以通过 npm 安装：

`1`	`npm install -g bun`

macOS Homebrew：

1
2

brew tap oven-sh/bun
brew install bun

Docker：

1
2

docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

Linux 用户要注意内核版本。README 提到强烈建议 Linux kernel 5.6 或更高，最低要求是 5.1。

升级到最新版：

`1`	`bun upgrade`

升级到 canary：

`1`	`bun upgrade --canary`

生产环境一般不建议直接用 canary，除非你是在验证新特性或排查特定 bug。

为什么 Bun 会快

Bun 的“快”主要来自几个层面。

第一，运行时启动快。

很多 CLI 工具和开发脚本的瓶颈不是长期 CPU 运算，而是进程启动、模块加载、TypeScript 转译和依赖解析。Bun 针对这些路径做了很多优化。

第二，包管理快。

bun install 的目标是替代 npm / yarn / pnpm 的依赖安装流程。它使用全局缓存和自己的 lockfile，安装大量依赖时通常能明显减少等待。

第三，TypeScript / JSX 开箱即用。

很多项目只是想运行一个 .ts 或 .tsx 脚本，传统 Node.js 工具链需要额外加 tsx、ts-node、Babel 或构建步骤。Bun 可以直接跑，减少了胶水工具。

第四，内置工具减少进程和配置切换。

测试、脚本、打包、运行都在同一个工具里，很多场景不用再在多个 CLI 之间切换。

但要注意，“Bun 很快”不等于每个项目都一定更快。真实效果取决于依赖类型、脚本逻辑、测试框架、构建配置、Node.js API 使用情况和 CI 缓存策略。

包管理：替代 npm / yarn / pnpm

Bun 可以直接安装依赖：

`1`	`bun install`

添加依赖：

`1`	`bun add react`

添加开发依赖：

`1`	`bun add -d typescript`

移除依赖：

`1`	`bun remove react`

查看依赖原因：

`1`	`bun why react`

安全检查：

`1`	`bun audit`

如果你从 npm 或 pnpm 迁移，重点要看：

bun.lock 是否进入版本控制。
CI 是否使用 bun install --frozen-lockfile。
私有 registry 和 .npmrc 是否兼容。
workspace 行为是否符合预期。
lifecycle scripts 是否会带来安全风险。
原本依赖 pnpm 特性的 monorepo 是否能平滑迁移。

小项目可以直接试。大型 monorepo 不建议一次性全切，可以先在单个 package 或 CI 的非关键任务里试。

运行脚本和 TypeScript

Bun 可以运行 package.json 里的脚本：

`1`	`bun run start`

也可以直接运行文件：

1
2

bun run index.ts
bun run index.tsx

这对工具脚本很方便。比如以前项目里有一堆：

scripts/build.ts
scripts/seed.ts
scripts/migrate.ts
scripts/check.ts

如果用 Node.js，通常要解决 TypeScript loader 或预编译问题。Bun 的直接运行能力可以让这些脚本更轻。

不过，如果脚本依赖 Node.js 特定行为，尤其是 loader、ESM/CJS 边界、原生模块、child process、文件监听和某些边缘 API，仍然要测试。

测试运行器

Bun 内置测试运行器：

`1`	`bun test`

它适合想减少 Jest / Vitest 配置的小项目，也适合把一些单元测试、工具测试、库测试迁移到更轻的运行方式。

迁移测试时重点关注：

expect 行为差异。
mock API 差异。
snapshot 行为。
DOM 测试环境。
测试发现规则。
覆盖率输出。
CI reporter 支持。

如果项目已经深度依赖 Jest 生态，比如大量自定义 matcher、复杂 mock、jsdom、babel-jest、ts-jest，迁移就不要太急。可以先让新模块用 bun test，旧测试继续保留原框架。

打包和构建

Bun 也提供 bundler，常见用法是：

`1`	`bun build ./src/index.ts --outdir ./dist`

它可以用于前端包、后端脚本、CLI 工具和库构建。Bun 文档里还覆盖了 loaders、plugins、macros、CSS、HTML、HMR、minifier、single-file executable 等方向。

适合优先尝试的场景：

小型前端工具。
Node.js CLI。
内部脚本。
单文件服务。
不依赖复杂 webpack loader 的项目。

谨慎迁移的场景：

复杂 webpack 插件链。
大量 Vite 插件。
深度依赖 Babel 转换。
特殊 CSS / asset pipeline。
微前端和模块联邦。
对构建产物 hash、chunk、兼容性要求很细的项目。

Bun bundler 很有吸引力，但构建工具迁移的风险通常比包管理更高，最好单独验证。

运行 HTTP 服务

Bun 提供 Bun.serve 来写 HTTP 服务：

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun")
  },
})

这对小型 API、内部服务、Webhook receiver、边缘风格服务很方便。Bun 还提供 WebSockets、Workers、Streams、SQLite、PostgreSQL、Redis、S3、TCP/UDP sockets 等 API。

但如果你已有 Express、Fastify、NestJS、Next.js、Hono、Elysia 等框架，也可以先看它们在 Bun 上的兼容程度，不必为了用 Bun 就重写服务。

更现实的路径是：

先用 Bun 做开发脚本和包管理。
再用 Bun 跑测试。
最后评估是否把运行时切到 Bun。

运行时迁移最需要谨慎，因为它直接影响生产服务行为。

和 Node.js 的关系

Bun 的目标之一是作为 Node.js 的 drop-in replacement，但“兼容”不是“完全等同”。

Node.js 生态已经积累了很多年，很多包依赖细微行为：

CJS / ESM 互操作。
Node 内置模块。
原生扩展。
npm lifecycle scripts。
文件系统边缘行为。
stream 和 Buffer 细节。
worker / child_process。
调试和 profiling。

Bun 在兼容性上进步很快，但生产迁移仍要以测试结果为准。

比较稳妥的判断方式：

你的测试能否在 Bun 下通过。
关键依赖是否支持 Bun。
构建产物是否一致。
CI 和本地表现是否一致。
线上运行是否有监控和回滚。
Docker 镜像和部署脚本是否稳定。

如果只是替换包管理器，风险较低；如果替换生产运行时，风险高很多。

适合哪些项目

Bun 很适合这些场景：

新的 JavaScript / TypeScript 小项目。
内部工具和脚本。
CLI 项目。
需要快速安装依赖的 CI。
希望减少工具链复杂度的前端项目。
对启动速度敏感的脚本和服务。
想用 TypeScript 开箱即跑的开发者。

暂时要谨慎的场景：

超大型 monorepo。
深度绑定 pnpm workspace 行为的项目。
依赖大量 Node.js 原生扩展的服务。
构建链路高度定制的前端工程。
对生产运行时一致性要求极高的后端。
依赖 Jest 复杂生态的测试套件。

一个保守但实用的策略是：先把 Bun 当作开发工具，而不是马上替代全部生产运行时。

迁移建议

如果想在现有项目试 Bun，可以按这个顺序：

在本地安装 Bun。
运行 bun install，观察依赖安装结果。
提交或暂存 bun.lock，避免和原 lockfile 混用造成混乱。
尝试 bun run <script> 跑常用脚本。
用 bun test 迁移少量测试。
在 CI 加一个非阻塞 Bun job。
确认没有兼容问题后，再考虑替换主安装流程。
最后再评估生产运行时是否切换。

对于团队项目，最好保留回滚路径：

迁移前保留原 npm / pnpm / yarn 流程。
CI 里同时跑一段时间。
不要在同一次改动里同时换运行时、包管理器、测试框架和打包器。
把迁移拆成小步骤，每一步都有可验证收益。

这样做虽然慢一点，但不容易把问题混在一起。

常见命令速查

安装：

`1`	`curl -fsSL https://bun.com/install \| bash`

升级：

`1`	`bun upgrade`

安装依赖：

`1`	`bun install`

添加依赖：

`1`	`bun add lodash`

运行脚本：

`1`	`bun run dev`

直接运行 TypeScript：

`1`	`bun run scripts/build.ts`

测试：

`1`	`bun test`

打包：

`1`	`bun build ./src/index.ts --outdir ./dist`

执行包命令：

`1`	`bunx cowsay 'Hello, world!'`

总结

Bun 的价值不只是“比 Node.js 快”。更重要的是，它把 JavaScript / TypeScript 开发里一堆分散工具收进了一个 bun 命令：运行时、包管理器、脚本运行器、测试运行器和打包器。

对新项目和内部工具来说，这种一体化体验很舒服：安装快、启动快、配置少，TypeScript 和 JSX 也能直接跑。对已有大型项目来说，Bun 更适合先从低风险环节切入，比如包安装、脚本和部分测试，再逐步验证构建和运行时。

如果你经常被 Node.js 工具链里的安装速度、配置碎片和测试启动时间折磨，Bun 值得认真试一下。但真正迁移生产服务时，还是要回到最朴素的工程判断：测试能不能过、依赖是否兼容、CI 是否稳定、线上有没有回滚。

参考链接：

Godot 游戏开发入门：从节点、场景到第一个 2D 小游戏

Sun, 17 May 2026 12:37:30 +0800

Godot 是一款开源游戏引擎，适合从 2D 小游戏、独立游戏原型，到中等规模的 3D 项目开发。

它最大的特点是轻量、开源、启动快，节点和场景系统非常清晰。对新手来说，Godot 的门槛通常比 Unity 低；对独立开发者来说，它不绑定商业授权模式，也更容易做出可控的小项目。

这篇文章用最少概念把 Godot 的入门路线讲清楚：你先理解节点和场景，再学 GDScript，最后用一个 2D 小游戏把输入、物理、碰撞、UI、音效和导出串起来。

先说结论

Godot 入门不要一上来就学大而全的引擎功能。

更合理的路线是：

先做 2D，不急着做 3D。
先理解节点和场景，不急着写复杂架构。
先学 GDScript，不急着上 C#。
先做一个能跑、能失败、能重开的小游戏。
再逐步补动画、音效、UI、关卡和导出。

只要做完一个完整小项目，你对 Godot 的理解会比刷十几个零散教程更稳。

Godot 适合什么人

Godot 很适合这几类人：

想从零开始学游戏开发。
想做 2D 独立游戏。
想快速做玩法原型。
不想被复杂商业引擎工具链压住。
想理解游戏引擎底层组织方式。
有一点 Python / JavaScript 经验，想快速上手脚本。

如果你的目标是大型 3A 画面、复杂商业团队管线、现成资产商店生态，Unity 或 Unreal 可能仍然更成熟。但如果目标是学习和做自己的游戏，Godot 非常适合起步。

安装和项目创建

Godot 的安装很简单。

到官网下载安装包，解压后直接运行即可。它不像很多大型引擎那样必须先装完整启动器，也不需要复杂账号流程。

新建项目时，建议先选：

Renderer：默认即可。
Project Name：用英文短横线或下划线。
路径：不要放在中文或空格特别多的目录里。
版本管理：建议从一开始就用 Git。

第一个项目可以叫：

`1`	`first-godot-game`

项目创建后，Godot 会进入编辑器。你需要先熟悉几个区域：

Scene：当前场景的节点树。
FileSystem：项目资源目录。
Inspector：选中节点的属性面板。
Script：脚本编辑区。
2D / 3D 视图：编辑画面和对象位置。

Godot 的核心：节点和场景

Godot 最重要的概念只有两个：节点和场景。

节点是功能单元。比如：

Node2D：2D 对象基础节点。
Sprite2D：显示图片。
CollisionShape2D：碰撞形状。
CharacterBody2D：可移动角色。
Camera2D：2D 摄像机。
AudioStreamPlayer：播放音频。
Label：显示文字。

场景是一组节点的组合。一个角色可以是一个场景，一个敌人可以是一个场景，一个关卡也可以是一个场景。

比如一个玩家角色场景可能长这样：

Player (CharacterBody2D)
├── Sprite2D
├── CollisionShape2D
└── Camera2D

这棵树的意思是：玩家本体负责移动，Sprite2D 负责显示角色图片，CollisionShape2D 负责碰撞，Camera2D 跟随玩家。

Godot 的思路就是：把游戏拆成很多可复用场景，再把场景组合成完整游戏。

第一个 2D 项目做什么

新手第一个项目不要做 RPG、开放世界、联机游戏或复杂平台跳跃。

建议做一个最小 2D 闪避游戏：

玩家可以上下左右移动。
敌人从屏幕边缘出现。
玩家碰到敌人就失败。
存活时间越长分数越高。
有开始按钮、失败界面和重新开始。

这个项目很小，但能覆盖 Godot 入门最重要的东西：

角色移动。
输入系统。
碰撞检测。
敌人生成。
UI 显示。
定时器。
音效。
场景切换。

做完它，你就已经跨过了“只会看教程，不知道怎么组织项目”的第一道坎。

玩家移动怎么写

在 Godot 里，玩家角色通常用 CharacterBody2D。

给 Player 节点挂一个脚本：

extends CharacterBody2D

@export var speed := 300.0

func _physics_process(delta):
    var direction := Vector2.ZERO

    direction.x = Input.get_axis("move_left", "move_right")
    direction.y = Input.get_axis("move_up", "move_down")
    direction = direction.normalized()

    velocity = direction * speed
    move_and_slide()

这段代码做了几件事：

读取水平和垂直方向输入。
把方向向量归一化，避免斜向移动更快。
把方向乘以速度，得到 velocity。
用 move_and_slide() 让角色移动并处理碰撞。

还需要在 Project Settings 里设置输入：

move_left  -> A / Left
move_right -> D / Right
move_up    -> W / Up
move_down  -> S / Down

Godot 的输入系统建议一开始就用 action，不要在代码里直接写死键盘按键。这样以后支持手柄、触屏或改键会方便很多。

碰撞和物理怎么理解

Godot 的碰撞不是只靠图片大小判断，而是靠碰撞形状。

常用节点有：

CollisionShape2D：给角色或敌人定义碰撞范围。
Area2D：检测进入、离开、重叠，适合触发器。
CharacterBody2D：适合玩家和会移动的角色。
RigidBody2D：适合受物理力影响的物体。
StaticBody2D：适合墙、地面、固定障碍。

入门阶段记住一个原则：

如果你要自己控制角色移动，用 CharacterBody2D。

如果你只想检测“玩家碰到敌人”，敌人可以用 Area2D，再监听信号：

1
2
3

func _on_body_entered(body):
    if body.name == "Player":
        get_tree().reload_current_scene()

后面项目变复杂时，可以改成发送 game_over 信号，而不是直接重载场景。新手阶段先跑通逻辑更重要。

场景实例化：让敌人不断出现

Godot 的场景可以当成“预制体”使用。

假设你有一个 Enemy.tscn，可以在主场景里用脚本生成它：

@export var enemy_scene: PackedScene

func spawn_enemy():
    var enemy = enemy_scene.instantiate()
    enemy.position = Vector2(800, randf_range(50, 550))
    add_child(enemy)

再配合 Timer 节点，每隔一段时间调用一次 spawn_enemy()，敌人就会不断生成。

这就是 Godot 项目常见组织方式：

一个场景负责一种对象。
主场景负责调度和组合。
需要时动态实例化子场景。

UI 和分数

Godot 的 UI 使用 Control 系列节点。

常用节点包括：

CanvasLayer：让 UI 固定在屏幕上，不跟随相机移动。
Label：显示文字。
Button：按钮。
Panel：面板背景。
VBoxContainer / HBoxContainer：自动排版。

分数可以先用存活时间来做：

var score := 0.0

func _process(delta):
    score += delta
    $CanvasLayer/ScoreLabel.text = str(int(score))

这样每秒增加 1 分。后面可以改成击败敌人、收集金币或完成关卡加分。

音效和反馈

小游戏好不好玩，很大一部分来自反馈。

即使画面很简单，也要加：

移动或点击音效。
碰撞音效。
得分音效。
失败音效。
屏幕震动或闪烁。
按钮 hover / pressed 状态。

Godot 里可以用 AudioStreamPlayer 播放音效：

`1`	`$HitSound.play()`

新手常犯的错误是只做功能，不做反馈。功能能跑只是第一步，玩家能不能感到“我做了一个动作，游戏回应了我”，才是游戏体验的开始。

文件怎么组织

项目一开始就建议整理目录：

res://
├── scenes/
│   ├── Main.tscn
│   ├── Player.tscn
│   └── Enemy.tscn
├── scripts/
│   ├── player.gd
│   └── enemy.gd
├── assets/
│   ├── sprites/
│   └── audio/
└── ui/
    └── GameOver.tscn

不要把所有资源都丢在根目录。小游戏阶段无所谓，项目稍微大一点就会混乱。

一个简单原则是：

场景放 scenes/。
脚本放 scripts/。
图片和音频放 assets/。
UI 单独放 ui/。

Godot 新手常见坑

第一个坑：节点选错。

能自己控制移动的角色用 CharacterBody2D，不是随便用 Node2D。触发检测用 Area2D，固定障碍用 StaticBody2D。

第二个坑：忘记碰撞形状。

只有图片没有碰撞体，游戏不会知道它们撞上了。

第三个坑：把按键写死。

不要直接判断 KEY_A，用输入 action。

第四个坑：场景职责混乱。

不要让一个脚本同时管玩家、敌人、UI、音效和关卡。新手可以简单，但不要所有东西都堆在 Main.gd。

第五个坑：一开始就做大项目。

第一个项目越小越好。只要完整，有开始、有失败、有重新开始，就比半途而废的大项目更有价值。

Godot 和 Unity 怎么选

如果你主要做 2D 独立游戏、教学项目、个人原型，Godot 非常舒服。

如果你需要庞大的资产商店、成熟商业插件、移动广告和商业化 SDK、成熟团队经验，Unity 生态仍然更强。

如果你要做高规格 3D、复杂渲染、影视级画面，Unreal 更适合。

对新手来说，不要把选引擎变成拖延。Godot 足够你做出大量完整小游戏。你真正需要先学会的是：

游戏循环。
输入响应。
碰撞和反馈。
场景组织。
状态管理。
资源和版本管理。

这些能力换到其他引擎也能用。

第一个项目的完成标准

你可以用这个清单判断自己是否真的入门：

玩家能移动。
有敌人或障碍。
有碰撞失败。
有分数或目标。
有开始界面。
有失败界面。
能重新开始。
有至少两个音效。
有简单动画或视觉反馈。
能导出一个可运行版本。

做到这里，你就不是“打开过 Godot”，而是真的完成了一个游戏闭环。

总结

Godot 入门的关键，不是把所有功能看一遍，而是先理解它的组织方式：节点组成场景，场景组成游戏，脚本驱动行为，信号连接事件，资源通过目录管理。

第一个项目建议从 2D 小游戏开始。玩家移动、敌人生成、碰撞失败、UI 分数、音效反馈、重新开始，这几个环节跑通之后，再去学动画树、TileMap、存档、状态机、3D、Shader 和导出优化。

游戏开发不是先学完引擎再开始做，而是在做小项目的过程中反复补概念。Godot 的优势正好在这里：它足够轻，能让你很快从“想做游戏”走到“真的跑起来”。

Ghostty 文档速读：安装、配置与日常使用要点

Fri, 15 May 2026 14:50:11 +0800

Ghostty 是一个新的终端模拟器，但它并不只是“又一个更快的终端”。按照官方文档的说法，它想同时兼顾三个方向：速度、功能和原生桌面体验。也就是说，它既希望有 GPU 加速和较好的渲染性能，也希望在 macOS 和 Linux 上尽量像一个真正的本地应用，而不是把所有交互都塞进自绘界面里。

如果你正在用 iTerm2、Kitty、Alacritty、WezTerm 或系统自带终端，Ghostty 最值得关注的地方不是某一个单点功能，而是它把“开箱即用”和“深度可配置”放在了一起。默认配置已经能直接使用；想继续折腾时，文档又给了配置文件、主题、快捷键、字体、Shell 集成和终端控制序列等完整入口。

先看定位

Ghostty 的核心定位可以概括为三句话：

它是跨平台终端模拟器，目前重点覆盖 macOS 和 Linux。
它使用平台原生 UI：macOS 端使用 Swift、AppKit 和 SwiftUI，Linux 端使用 Zig 和 GTK4。
它的终端核心是 libghostty，GUI 应用围绕这个共享核心构建。

这个设计会影响日常体验。比如标签页、分屏、错误提示、窗口状态恢复、系统快捷键等能力，不是简单做成“看起来像桌面应用”的组件，而是尽量贴近所在系统的交互习惯。macOS 和 Linux 默认快捷键也会按各自平台约定区分。

安装方式：macOS 最直接，Linux 看发行版

官方预构建二进制主要面向 macOS。最普通的安装方式是下载 .dmg，打开后把 Ghostty 拖到 Applications 目录。Homebrew 用户也可以用社区维护的 cask：

`1`	`brew install --cask ghostty`

Linux 的情况更分散。Ghostty 文档把不同发行版的包管理器、社区二进制和源码构建分开说明。Arch、Alpine、Gentoo、NixOS、Snap、Solus、Void 等都有对应路径；如果发行版没有官方或可信仓库，文档更倾向于让用户从源码构建，而不是随意安装第三方二进制。

这点对服务器和工作机尤其重要：终端模拟器会处理大量输入输出、剪贴板、链接、SSH 会话和本地文件路径。安装源最好保守一点，优先选官方 macOS 包、发行版仓库或自己能审计来源的构建流程。

配置：先别急着复制一大份 dotfiles

Ghostty 的配置哲学是“零配置可用”。默认字体内置 JetBrains Mono，也带有 Nerd Font 支持；大多数用户第一次打开就能正常工作。文档甚至建议，如果你发现必须配置某个非主观选项才舒服，可以先考虑它是不是应该成为默认行为。

真正需要定制时，Ghostty 使用文本配置文件。当前配置文件名是 config.ghostty，旧版本也支持 config。常见路径包括：

$XDG_CONFIG_HOME/ghostty/config.ghostty
$XDG_CONFIG_HOME/ghostty/config
$HOME/.config/ghostty/config.ghostty
$HOME/.config/ghostty/config

macOS 还会读取：

1
2

$HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty
$HOME/Library/Application Support/com.mitchellh.ghostty/config

配置语法非常直接，就是 key = value。例如：

font-family = JetBrains Mono
font-size = 14
theme = light:Rose Pine Dawn,dark:Rose Pine
keybind = ctrl+shift+t=new_tab

一个实用建议是：不要一开始就找别人的完整配置照抄。更稳的方式是先裸跑几天，只改三类东西：字体、字号和主题。等你真的发现快捷键、分屏、窗口、Shell 集成有摩擦，再逐项加配置。

文档查询：本地也能查完整配置

Ghostty 的配置项很多，官方文档把它们集中在 Option Reference。除了网页，安装后也可以从本地查配置参考：

`1`	`ghostty +show-config --default --docs`

这个命令会把默认配置和文档输出到标准输出，适合接到分页器里慢慢搜：

`1`	`ghostty +show-config --default --docs \| less`

查看可用字体时可以用：

`1`	`ghostty +list-fonts`

查看内置和可用主题时可以用：

`1`	`ghostty +list-themes`

查看默认快捷键时可以用：

`1`	`ghostty +list-keybinds --default`

这些命令比在网上复制片段更可靠，因为它们来自你当前安装的 Ghostty 版本。

快捷键：把“动作”当成核心概念

Ghostty 的快捷键配置格式是：

`1`	`keybind = trigger=action`

trigger 是按键触发方式，action 是 Ghostty 执行的动作。比如新建标签页、关闭当前 surface、重新加载配置、跳转到提示符等，都属于 action。这个模型的好处是清晰：你不是在“改某个菜单项”，而是在把一个输入序列绑定到一个动作。

配置改完后，可以在运行时重新加载。默认快捷键是：

Linux：ctrl+shift+,
macOS：cmd+shift+,

不过并不是所有配置都能即时生效。有些选项只影响新建终端，有些需要完整重启。遇到“配置写了但没变化”时，先查对应选项说明，比反复怀疑语法更省时间。

主题和字体：先用内置，再做细调

Ghostty 自带大量主题，并支持按系统浅色、深色模式切换不同主题：

`1`	`theme = light:Rose Pine Dawn,dark:Rose Pine`

主题也可以来自自定义文件。文档提醒得很明确：主题文件本质上也是 Ghostty 配置文件，可以设置很多配置项，所以不要随便使用不可信来源的主题。

字体方面，font-family 可以重复多次，用来指定 fallback 字体。对多语言环境很实用，比如主字体负责英文和符号，后续字体补中文、日文或其他字符。遇到 emoji、粗体、斜体、连字等显示细节时，再去 Option Reference 里查对应选项即可。

Shell 集成：SSH 用户尤其应该看

Ghostty 支持自动注入 shell integration，覆盖 bash、elvish、fish、nushell 和 zsh。启用后，一些体验会更自然，比如：

新终端从前一个终端的工作目录打开。
复杂提示符 resize 时可以重绘，而不是被错误回流。
可以通过提示符标记在命令输出之间跳转。
在提示符处支持更符合编辑习惯的光标行为。

如果不想自动注入，可以在配置里关闭：

`1`	`shell-integration = none`

更值得注意的是 SSH。Ghostty 使用 xterm-ghostty 作为 TERM，但很多远程主机还没有对应的 terminfo。文档提供了 ssh-env 和 ssh-terminfo 两个 shell integration 功能，默认关闭，可以按需启用：

`1`	`shell-integration-features = ssh-env,ssh-terminfo`

如果你经常连接旧服务器、容器、跳板机或严格管理的生产环境，建议先读完官方的 Terminfo 和 Shell Integration 文档，再决定是否启用这些功能。终端能力协商看起来不起眼，但一旦出问题，表现可能是颜色异常、快捷键失灵、全屏程序显示错乱。

我的上手顺序

如果只是想判断 Ghostty 是否适合自己，可以按这个顺序试：

安装后不写配置，直接用一天。
只调整 font-family、font-size 和 theme。
用 ghostty +list-keybinds --default 看默认快捷键，而不是先搬运别人的快捷键表。
如果常用 SSH，优先检查远程主机的 terminfo 兼容问题。
最后再处理分屏、窗口、透明度、标题栏、背景图等视觉和工作流偏好。

Ghostty 文档写得比较工程化，适合把它当成“配置参考手册”而不是“宣传页”阅读。对多数用户来说，真正的判断标准也很简单：默认体验是否已经舒服，日常编辑器、Shell、SSH、tmux 或 Zellij 是否稳定。如果这几件事都顺，Ghostty 就值得进入你的长期终端候选列表。

参考链接

VS Code 切换界面语言的方法：中文、英文和其他语言

Fri, 08 May 2026 13:28:14 +0800

VS Code 支持多种界面语言。常见做法是先安装对应语言包，再通过命令面板选择显示语言；如果需要固定某种语言，也可以手动修改 argv.json 中的 locale。

这套方法不仅适用于简体中文，也适用于英文、繁体中文、日文、韩文、法文、德文、西班牙文等语言。

安装对应语言包

如果要切换到非英文界面，通常需要先安装语言包。

打开 VS Code 左侧扩展面板，也可以使用快捷键 Ctrl+Shift+X。
在搜索框中输入目标语言，例如 Chinese、Japanese、Korean、French。
选择对应语言包，点击 Install。
安装完成后，按提示重启 VS Code。

简体中文常用语言包是 Chinese (Simplified)，繁体中文常用语言包是 Chinese (Traditional)。

通过命令面板切换语言

这是最推荐的切换方式，适合大多数用户。

打开命令面板：Ctrl+Shift+P。
输入 Configure Display Language。
选择 Configure Display Language 命令。
在列表中选择要使用的语言。
按提示重启 VS Code。

重启后，菜单、设置页和常见提示会切换到所选语言。如果列表里没有目标语言，先到扩展面板安装对应语言包。

通过 argv.json 手动指定语言

如果命令面板切换失败，或者想明确固定显示语言，可以直接修改 VS Code 的运行时参数文件。

打开命令面板：Ctrl+Shift+P。
输入并选择 Preferences: Configure Runtime Arguments。
找到或添加 locale 配置项。
把值改成目标语言代码。
保存后重启 VS Code。

例如切换为英文：

1
2
3

{
  "locale": "en"
}

切换为简体中文：

1
2
3

{
  "locale": "zh-cn"
}

切换为日文：

1
2
3

{
  "locale": "ja"
}

argv.json 是 JSON 文件，修改时要注意逗号和引号。配置写错时，VS Code 可能无法正确读取语言设置。

常用界面语言代码

显示语言	locale
English (US)	`en`
简体中文	`zh-cn`
繁体中文	`zh-tw`
French	`fr`
German	`de`
Italian	`it`
Spanish	`es`
Japanese	`ja`
Korean	`ko`
Russian	`ru`
Portuguese (Brazil)	`pt-br`
Turkish	`tr`
Bulgarian	`bg`
Hungarian	`hu`

语言没有生效怎么办

可以按下面顺序排查：

确认目标语言包已经安装。
确认 locale 写的是正确语言代码，例如简体中文是 zh-cn，不是 zh-CN。
修改语言后完整关闭并重新打开 VS Code。
如果手动改过 argv.json，检查 JSON 语法是否正确。
如果配置混乱，可以删除 locale 项，再通过 Configure Display Language 重新选择。

一般来说，通过 Configure Display Language 切换最省事；只有在需要强制指定语言或命令面板切换不生效时，才建议手动修改 argv.json。

参考资料

VScode：将VScode界面的显示语言改为简体中文，切换VScode界面的显示语言

opencode、Claude Code、Codex 有什么区别？开源 AI 编程工具使用指南

Fri, 08 May 2026 08:33:37 +0800

opencode 是 anomalyco 开源的 AI Coding Agent。它的定位很直接：让开发者在终端里使用一个可编程、可扩展、可接入多家模型的代码助手。

如果把它和 Claude Code、Codex 放在一起看，三者解决的是同一类问题：让 AI 进入真实代码库，理解上下文，修改文件，运行命令和测试。但它们的产品取向不一样。

opencode 更强调开源、多模型和终端 TUI；Claude Code 更强调 Anthropic 模型生态和本地工程协作；Codex 则是 OpenAI 的 AI coding agent，可以在终端、IDE、Codex app 和云端任务里使用。

opencode 适合谁

opencode 更适合这几类开发者：

想在终端里完成代码修改、项目分析和工程任务的人。
希望 AI Coding Agent 不绑定单一模型提供商的人。
偏好开源工具，想自己审计、扩展或二次开发的人。
已经习惯 Neovim、TUI、命令行工作流的人。
希望以后用桌面端、移动端或其他客户端远程驱动同一个编码代理的人。

它的重点不是做一个聊天窗口，而是把 AI 编程能力放进开发者原本使用的终端和项目目录里。

安装方式

官方 README 提供了多种安装方式。

# 直接安装
curl -fsSL https://opencode.ai/install | bash

# npm
npm i -g opencode-ai@latest

# Windows
scoop install opencode
choco install opencode

# macOS 和 Linux
brew install anomalyco/tap/opencode
brew install opencode

# Arch Linux
sudo pacman -S opencode
paru -S opencode-bin

# 其他方式
mise use -g opencode
nix run nixpkgs#opencode

官方也提醒，安装前最好先移除 0.1.x 之前的旧版本，避免旧版本残留造成问题。

安装脚本会按优先级选择安装目录：

$OPENCODE_INSTALL_DIR
$XDG_BIN_DIR
$HOME/bin
$HOME/.opencode/bin

如果需要指定路径，可以这样写：

1
2

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

桌面应用还在 Beta

除了命令行工具，opencode 也提供桌面应用，目前仍处于 Beta。可以从 GitHub Releases 或 opencode.ai/download 下载。

桌面端覆盖这些平台：

平台	文件
macOS Apple Silicon	`opencode-desktop-mac-arm64.dmg`
macOS Intel	`opencode-desktop-mac-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb`、`.rpm` 或 `.AppImage`

macOS 和 Windows 也可以通过包管理器安装桌面端。

# macOS
brew install --cask opencode-desktop

# Windows
scoop bucket add extras
scoop install extras/opencode-desktop

两种内置 Agent 模式

opencode 内置两种 Agent，可以通过 Tab 键切换。

build 是默认模式，拥有完整开发权限，适合直接修改代码、运行命令和推进工程任务。

plan 是只读模式，更适合分析陌生代码库、理解项目结构、制定修改方案。它默认拒绝文件编辑，并且在运行 bash 命令前会询问。

另外，opencode 还带有一个 general 子 Agent，用于复杂搜索和多步骤任务。用户可以在消息中输入 @general 调用。

这个设计比较实用：真正动手前先用 plan 看清楚项目，需要改代码时再切到 build。对于大型仓库，读写权限分开能减少误操作。

Codex 是什么

Codex 是 OpenAI 的 AI coding agent，用来帮助开发者写代码、审查代码、修复 bug 和交付工程任务。

和单纯的代码补全工具不同，Codex 更接近一个可以操作代码库的 Agent。它可以在本地工具里和你结对，也可以把任务委托到云端执行。OpenAI 官方资料里提到，Codex 可以通过 CLI、IDE、Codex app、ChatGPT/Codex 云端等不同入口使用。

对开发者来说，Codex 的重点有几处：

可以读取代码库、编辑文件、运行命令和测试。
支持终端、IDE、应用和云端等多种使用界面。
适合修 bug、写功能、重构、迁移、代码审查和测试补齐。
更偏 OpenAI 账户、模型和 Codex 产品体系。
云端任务适合并行处理多个相对清晰的工程任务。

如果 opencode 更像一个开放的终端代理框架，Codex 更像 OpenAI 提供的一整套 AI 编程工作台：本地可以结对，云端可以委托，团队可以把它接入更长的工程流程。

三者核心区别

opencode、Claude Code、Codex 都是 AI 编程工具，但选择时可以先看这几个维度。

工具	核心定位	主要优势	更适合
`opencode`	开源 AI Coding Agent	开源、多模型、TUI、客户端/服务器架构	想要开放工具链、可替换模型、偏终端工作流的开发者
`Claude Code`	Anthropic 的命令行编程工具	Claude 模型体验、代码理解、长上下文、工程任务协作	已经使用 Claude/Anthropic 生态，希望本地推进代码任务的开发者
`Codex`	OpenAI 的 AI coding agent	CLI、IDE、Codex app、云端任务、多 Agent 工作流	已经使用 ChatGPT/OpenAI，希望本地结对和云端委托并用的团队

简单说，opencode 的关键词是“开源和可替换”，Claude Code 的关键词是“Claude 生态和本地工程代理”，Codex 的关键词是“OpenAI 生态和多入口协作”。

和 Claude Code 的区别

opencode 的官方 FAQ 直接把 Claude Code 拿来对比。两者能力上很接近，但差异主要在这几处。

第一，opencode 是 100% 开源项目，代码托管在 GitHub，并使用 MIT license。

第二，opencode 不绑定单一模型提供商。它推荐 OpenCode Zen 提供的模型，但也可以搭配 Claude、OpenAI、Google 或本地模型。对开发者来说，这意味着模型成本、能力和可用性变化时，不必被某一个平台锁住。

第三，opencode 内置可选的 LSP 支持。对代码补全、跳转、诊断和项目理解来说，LSP 是非常关键的基础能力。

第四，opencode 更强调 TUI。它由 Neovim 用户和 terminal.shop 的创建者打造，产品重心明显放在终端体验上。

第五，opencode 采用客户端/服务器架构。也就是说，opencode 可以在你的电脑上运行，未来由 TUI、桌面端、移动端或其他客户端来控制。TUI 只是其中一种前端形态。

什么时候选 opencode、Claude Code 或 Codex

如果你已经在使用 Claude Code 或 Codex，opencode 不一定是立刻替换它们的工具。更合理的看法是：它提供了一个开源、可替换模型、偏终端的选择。

可以优先考虑 opencode 的场景包括：

你希望 AI 编程工具尽量开源。
你不想把工作流绑定在某个模型供应商上。
你希望用同一个工具测试 Claude、OpenAI、Google 或本地模型。
你喜欢 TUI，不希望主要工作流被桌面应用或网页应用打断。
你关注客户端/服务器架构带来的远程控制能力。

可以优先考虑 Claude Code 的场景包括：

你主要使用 Claude 模型。
你重视长上下文、代码理解和复杂工程任务协作。
你希望在本地仓库中持续推进修改、测试和重构。
你更信任 Anthropic 对 Claude Code 的默认产品体验。

可以优先考虑 Codex 的场景包括：

你已经在使用 ChatGPT 或 OpenAI 账户体系。
你希望同一个 coding agent 覆盖终端、IDE、桌面应用和云端任务。
你想把较清晰的 bug 修复、功能开发、迁移、测试补齐交给云端并行处理。
你需要代码审查、后台任务、团队协作和多 Agent 工作流。

如果你更看重官方闭环体验、模型默认配置、企业管理和现成集成，Claude Code 或 Codex 可能更省心；如果你更看重可控性、开放性和 provider-agnostic，opencode 更值得关注。

需要注意的地方

opencode、Claude Code 和 Codex 都发展很快，GitHub release、安装命令、桌面端文件名、模型可用性和套餐权限都可能变化。实际安装和选型前，最好直接查看各自官方 README、文档和发布页面。

另外，它的桌面应用仍然标注为 Beta，不适合默认当作稳定生产工具。对于日常工程任务，终端版仍然是更主要的入口。

从工具趋势看，opencode 代表的是 AI Coding Agent 的开放工具链方向：模型可以替换，客户端可以替换，核心代理能力尽量开放。Codex 和 Claude Code 则更像模型公司把 coding agent 做成完整产品入口。对开发者来说，这两条路线会长期并存。

参考链接

opencode GitHub：https://github.com/anomalyco/opencode
opencode 官网：https://opencode.ai
opencode 文档：https://opencode.ai/docs
opencode Releases：https://github.com/anomalyco/opencode/releases
OpenAI Codex：https://openai.com/codex/
Using Codex with your ChatGPT plan：https://help.openai.com/en/articles/11369540-codex-in-chatgpt
OpenAI Codex CLI Getting Started：https://help.openai.com/en/articles/11096431-openai-codex-ci-getting-started

uv 安装指南：macOS、Linux、Windows、pipx、Homebrew 和 WinGet 怎么选

Thu, 07 May 2026 23:02:49 +0800

uv 是 Astral 推出的 Python 工具链管理器，可以用来管理 Python 版本、虚拟环境、依赖、脚本、项目和工具。它的安装方式很多，官方文档提供了独立安装脚本，也支持 PyPI、Homebrew、WinGet、Scoop、Docker、GitHub Releases 和 Cargo。

如果只是想快速安装，优先用官方独立安装脚本。如果你希望通过系统包管理器维护版本，就用 Homebrew、WinGet 或 Scoop。如果你已经习惯 Python 工具隔离安装，可以用 pipx。

快速选择

场景	推荐方式	命令
macOS / Linux 快速安装	官方独立安装脚本	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux 没有 curl	官方脚本 + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Windows 快速安装	PowerShell 安装脚本	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Python 工具隔离安装	pipx	`pipx install uv`
临时或传统 Python 安装	pip	`pip install uv`
macOS 包管理	Homebrew	`brew install uv`
macOS MacPorts 用户	MacPorts	`sudo port install uv`
Windows 包管理	WinGet	`winget install --id=astral-sh.uv -e`
Windows Scoop 用户	Scoop	`scoop install main/uv`
Rust 用户	Cargo	`cargo install --locked uv`

最推荐的通用方案：

macOS / Linux：官方独立安装脚本；
Windows：官方 PowerShell 安装脚本或 WinGet；
已经使用 pipx 管理 Python CLI 工具：pipx install uv。

macOS 和 Linux：官方安装脚本

官方最直接的安装方式是用 curl 下载脚本并交给 sh 执行：

`1`	`curl -LsSf https://astral.sh/uv/install.sh \| sh`

如果系统没有 curl，可以用 wget：

`1`	`wget -qO- https://astral.sh/uv/install.sh \| sh`

如果想安装指定版本，可以把版本号放进 URL。比如官方示例中的 0.11.11：

`1`	`curl -LsSf https://astral.sh/uv/0.11.11/install.sh \| sh`

这个方式适合绝大多数个人开发环境。它的优点是简单、跨平台、和 uv 官方更新机制配合最好。

安装脚本会把 uv、uvx 等二进制文件安装到用户目录下，并可能修改 shell profile，让命令可以直接在终端中使用。如果你不希望安装器修改 PATH，可以参考官方 installer 选项，例如设置 UV_NO_MODIFY_PATH=1。

Windows：PowerShell 安装脚本

Windows 官方安装方式是用 PowerShell 执行安装脚本：

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

如果要安装指定版本，也可以把版本号放进 URL：

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.11/install.ps1 \| iex"`

这里的 ExecutionPolicy ByPass 是为了允许从互联网获取并执行安装脚本。安全习惯上，执行前可以先查看脚本内容：

`1`	`powershell -c "irm https://astral.sh/uv/install.ps1 \| more"`

如果你习惯 Windows 包管理器，也可以优先用 WinGet 或 Scoop。

用 pipx 安装

官方文档提到，uv 发布到了 PyPI。如果从 PyPI 安装，推荐放进隔离环境，例如用 pipx：

`1`	`pipx install uv`

这个方式适合已经把 pipx 当作 Python CLI 工具管理器的人。它可以避免把 uv 和当前项目环境混在一起。

如果没有 pipx，也可以直接用 pip：

`1`	`pip install uv`

但要注意：uv 在许多平台上提供预构建 wheel。如果某个平台没有对应 wheel，就会从源码构建，这时需要 Rust 工具链。

我的建议是：个人机器上，pipx install uv 比 pip install uv 更干净；项目环境里，不建议把 uv 当作项目依赖安装。

Homebrew、MacPorts、WinGet 和 Scoop

如果你更喜欢系统包管理器，uv 也支持常见渠道。

macOS 上用 Homebrew：

`1`	`brew install uv`

MacPorts 用户可以用：

`1`	`sudo port install uv`

Windows 上用 WinGet：

`1`	`winget install --id=astral-sh.uv -e`

Scoop 用户可以用：

`1`	`scoop install main/uv`

这些方式的好处是统一交给系统包管理器维护。缺点是升级节奏取决于对应包源，而不是 uv 官方安装脚本。

Docker、GitHub Releases 和 Cargo

uv 还提供 Docker 镜像，地址在 GitHub Container Registry：

`1`	`ghcr.io/astral-sh/uv`

这适合 CI、Dockerfile、构建镜像和临时运行环境。实际使用时，建议再看官方 Docker 集成文档。

如果你想手动下载二进制文件，可以从 GitHub Releases 获取。每个 release 页面通常包含支持平台的二进制文件，也会说明如何用 GitHub 地址调用独立安装器。

Rust 用户也可以从 crates.io 安装：

`1`	`cargo install --locked uv`

但这个方式会从源码构建，需要兼容的 Rust 工具链。除非你明确需要从 Rust 生态安装，否则普通用户不必优先选 Cargo。

升级 uv

如果 uv 是通过官方独立安装脚本安装的，可以用自更新命令：

`1`	`uv self update`

官方提示说，更新 uv 会重新运行安装器，并可能修改 shell profile。如果不希望更新时修改 PATH，可以设置：

`1`	`UV_NO_MODIFY_PATH=1`

如果你是通过其他方式安装的，就应该用对应包管理器升级。比如用 pip 安装，就用：

`1`	`pip install --upgrade uv`

Homebrew、WinGet、Scoop、MacPorts 也应该走各自的升级命令。

启用 shell 自动补全

uv 支持 shell 自动补全。官方文档建议先用下面命令确认当前 shell：

`1`	`echo $SHELL`

Bash：

`1`	`echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uv generate-shell-completion fish \| source' > ~/.config/fish/completions/uv.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

如果你也经常用 uvx，可以单独启用 uvx 补全。

Bash：

`1`	`echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uvx --generate-shell-completion fish \| source' > ~/.config/fish/completions/uvx.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

配置后需要重启 shell，或者重新加载对应配置文件。

卸载 uv

如果要卸载 uv，可以先清理缓存和 uv 存储的数据：

1
2
3

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

然后删除二进制文件。

macOS / Linux：

`1`	`rm ~/.local/bin/uv ~/.local/bin/uvx`

Windows：

1
2
3

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

官方文档还提醒：0.5.0 之前，uv 会安装到 ~/.cargo/bin。如果你从早期版本升级过，旧二进制文件可能仍然留在那里，需要手动删除。

安装后先做什么

安装完成后，建议先确认版本：

`1`	`uv --version`

然后可以从几个常见任务开始：

uv python install
uv venv
uv pip install requests
uvx ruff --version

如果你是新项目，可以进一步学习：

uv init：初始化项目；
uv add：添加依赖；
uv sync：同步环境；
uv run：在项目环境中运行命令；
uvx：临时运行 Python CLI 工具。

我的建议

个人开发机上，优先使用官方独立安装脚本，因为它最贴近 uv 官方文档，也支持 uv self update。

Windows 用户如果不想执行远程脚本，可以用 WinGet 或 Scoop。macOS 用户如果习惯所有工具都交给 Homebrew 管理，可以直接 brew install uv。

已经使用 pipx 管理 Python CLI 工具的人，可以用 pipx install uv。但不建议在具体项目虚拟环境里用 pip install uv，这样容易把工具链和项目依赖混在一起。

如果是 CI 或容器构建，优先看 Docker 和 GitHub Releases，根据镜像构建流程固定版本。

Awesome Codex Skills：给 Codex CLI 扩展技能的社区清单

Thu, 07 May 2026 20:19:15 +0800

ComposioHQ 的 awesome-codex-skills 是一个面向 Codex CLI 的社区技能清单。它的价值不在于再写一堆提示词模板，而是把一类可重复的工作流程整理成可安装、可复用、可维护的 Skill。

如果你已经把 Codex 当成日常开发搭档，这类仓库的意义会很直接：把经常重复讲的规则、命令、资料入口和操作步骤沉淀下来，下次只要调用对应技能，Codex 就能按同一套上下文继续工作。

这个仓库解决什么问题

Codex Skills 可以理解成给 Codex CLI 增加“专门工作模式”的方式。普通提示词适合临时说明一次需求，Skill 更适合长期复用。

比如你经常需要：

按固定格式生成提交信息；
查阅某类 API 文档；
运行特定项目的测试和部署命令；
按团队规范重写文章、翻译文档或整理资料；
调用外部工具完成重复性的开发辅助任务。

这些内容如果每次都重新输入，很快就会变成负担。Skill 的思路是把这些规则放进一个独立目录里，核心通常是一份 SKILL.md，必要时再配合脚本、模板、参考资料或资产文件。Codex 在被触发时读取这份说明，然后按照里面定义的流程执行。

和普通提示词有什么不同

普通提示词更像一次性指令，适合告诉模型“这次怎么做”。Skill 更像一个小型操作手册，适合告诉 Codex“以后遇到这类任务都按这个方式做”。

它的优势主要有三个：

可复用：常用工作流不用反复复制粘贴。
可审查：技能文件通常是本地 Markdown，可以直接打开、修改和版本管理。
可扩展：复杂技能可以带脚本、模板和参考资料，不只是自然语言说明。

这也是 awesome-codex-skills 这类清单的价值所在：它帮你集中发现已经写好的技能，再根据自己的工作习惯挑选、安装和改造。

如何安装和使用

仓库提供了安装脚本，也支持手动安装。典型流程是先克隆仓库，再运行安装脚本：

1
2
3

git clone https://github.com/ComposioHQ/awesome-codex-skills.git
cd awesome-codex-skills
python install.py

如果你只想试用少数技能，建议先看清每个技能目录里的 SKILL.md，确认它会读取哪些资料、运行哪些脚本、修改哪些文件，再安装到本地 Codex skills 目录。

安装之后，Codex 可以在合适的任务中自动匹配技能，也可以通过明确点名的方式调用。对长期使用者来说，更实用的方式往往是：先安装一个社区技能，再把里面的说明改成自己的项目规范。

适合关注哪些技能

这类仓库里最值得优先看的，不一定是名字最酷的技能，而是能稳定减少重复劳动的技能。

我会优先关注几类：

开发流程类：代码审查、测试、提交、发布、依赖检查。
文档处理类：重写、翻译、摘要、结构化整理。
工具集成类：把 Codex 和外部服务、API、命令行工具连接起来。
项目规范类：把团队约定、目录结构、命名规则、部署步骤写进固定流程。

如果一个技能只是把一句提示词包装了一下，价值有限；如果它能把“查资料、判断、执行、验证、输出”串成稳定流程，就值得长期保留。

使用时要注意什么

社区技能虽然方便，但不要把它当成黑盒直接运行。尤其是带脚本的 Skill，安装前最好先检查三件事：

SKILL.md 里要求 Codex 做什么；
是否包含会访问网络、读写文件或调用外部服务的脚本；
默认路径、命令和权限是否适合你的本地环境。

Skill 本质上是在扩大 Codex 的行动边界。写得好，它会让 Codex 更像熟悉你项目的同事；写得粗糙，它也可能把不适合你的规则带进工作流。所以最理想的用法不是“装很多”，而是“装少数、改到顺手、长期维护”。

我的判断

awesome-codex-skills 值得收藏，尤其适合已经开始用 Codex CLI 做真实开发、文档或自动化任务的人。它不是官方能力本身，而是一个社区整理的技能入口：你可以从里面找灵感，也可以把常用流程改造成自己的本地技能库。

对重度用户来说，Codex Skills 的重点不是让 AI 多记一点东西，而是让 AI 在同类任务中少走弯路。把规则写成 Skill，等于把一次次临时沟通沉淀成可复用的工作基础设施。

Warp 开源：从终端到 Agentic Development Environment

Thu, 07 May 2026 20:15:08 +0800

warpdotdev/warp 是 Warp 的开源客户端仓库。Warp 官方现在把它定位为一个“从终端生长出来的 agentic development environment”，也就是以终端为基础，但把 AI coding agent、代码库索引、任务管理和开发工作流放进同一个环境里。

这不是一个普通的终端模拟器开源仓库。它更像是在回答一个问题：当 Claude Code、Codex、Gemini CLI 这类 agent 越来越常见时，终端本身要不要变成一个能调度、观察和管理 agent 的开发环境？

Warp 的答案是：要。

这个仓库现在是什么状态

截至 2026 年 5 月 7 日查看，warpdotdev/warp 是公开仓库，GitHub 页面显示约 56k stars、4.1k forks。仓库 README 说明，Warp 的客户端代码已经开源，并欢迎社区贡献。

仓库的主语言是 Rust。GitHub 语言统计里，Rust 占比超过 98%。这和 Warp 的定位一致：它不是网页壳，而是一个跨平台的原生开发工具。

README 中有几个信息点很重要：

Warp 是一个 agentic development environment, born out of the terminal。
它可以使用内置 coding agent，也可以接入 Claude Code、Codex、Gemini CLI 等外部 CLI agent。
OpenAI 是新开源 Warp 仓库的 founding sponsor。
仓库中的 agentic management workflows 由 GPT models 驱动。
Warp UI 框架相关 crate 使用 MIT license，其余代码使用 AGPL v3。

这些信息说明，Warp 开源不是单纯把一个终端放出来，而是把它作为“agent 工作流实验场”来运营。

Warp 不只是终端

传统终端主要解决三个问题：

启动 shell。
执行命令。
显示输出。

Warp 早期的差异化，是让终端更现代：命令块、补全、历史、协作、UI 化交互、跨平台体验。现在它的重心继续往前走，开始围绕 AI agent 组织开发流程。

从 README 看，Warp 不再只强调“更好用的 terminal”，而是强调：

内置 coding agent。
支持外部 CLI agent。
issue triage。
spec 编写。
PR review。
contributor coordination。
可观察的 agent sessions。

也就是说，Warp 想把终端从“你输入命令的地方”，变成“你和多个 agent 一起工作的地方”。

Oz 和开源项目管理

README 里多次提到 Oz。

Warp 的贡献概览页面可以看到成千上万个 Oz agents 在做 issue triage、写 specs、实现改动、review PR。这个设计很有意思，因为它把 AI agent 从“帮个人写代码”扩展到了“帮开源项目管理协作”。

传统开源项目最难的不是写代码，而是维护：

issue 太多，没人分类。
bug 和 feature request 混在一起。
新贡献者不知道哪些任务能做。
PR review 压力大。
维护者很难持续跟进社区讨论。

Warp 的思路是，让 agent 先承担一部分项目管理和协作工作。README 中还提到 Oz for OSS，这是面向维护者的合作计划，用于把类似 agentic open-source management workflows 带到其他开源仓库。

这说明 Warp 的野心不只是终端产品本身，也包括探索 AI 时代开源维护的新模式。

仓库结构和技术栈

从仓库结构看，Warp 是一个大型 Rust 项目。

根目录里能看到：

app/：主应用相关代码。
crates/：核心 Rust crates。
assets/：资源文件。
command-signatures-v2/：命令签名相关内容。
docker/、script/、resources/、specs/ 等工程目录。
.claude/、.warp/、.agents/skills 等 agent 相关配置。

WARP.md 里给出了更详细的工程说明。它提到 Warp 是 Rust-based terminal emulator，并使用一个自研 UI 框架 WarpUI。

主要模块可以粗略理解为：

app/：终端模拟、shell 管理、AI 集成、Drive、认证、设置、workspace 和 session。
crates/warp_core/：核心工具和平台抽象。
crates/editor/：文本编辑功能。
crates/warpui/ 和 crates/warpui_core/：自研 UI 框架。
crates/ipc/：进程间通信。
crates/graphql/：GraphQL 客户端和 schema。

WARP.md 还提到几个架构特点：

Entity-Handle system。
模块化 workspace 结构。
macOS、Windows、Linux 跨平台，以及 WASM target。
AI integration，包含 Agent Mode、上下文感知和代码库索引。
Warp Drive 云同步。

这说明 Warp 的复杂度已经接近一个完整 IDE，而不是传统意义上的轻量 terminal。

本地构建方式

README 给出的本地构建方式很简洁：

1
2
3

./script/bootstrap
./script/run
./script/presubmit

其中：

./script/bootstrap：执行平台相关初始化。
./script/run：构建并运行 Warp。
./script/presubmit：执行格式化、clippy 和测试等提交前检查。

WARP.md 里还列出了更细的命令：

cargo run
cargo bundle --bin warp
cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2
cargo fmt
cargo clippy --workspace --all-targets --all-features --tests -- -D warnings

如果要给 Warp 提交代码，./script/presubmit 基本是必须跑的。

贡献流程

Warp 的贡献流程不是简单“发 PR 就行”。

README 描述了一个从 issue 到 PR 的轻量流程：

先搜索已有 issue。
没有重复再提交 bug 或 feature request。
维护者会 review issue，并可能打上 readiness label。
ready-to-spec 表示设计可以被贡献者展开成 spec。
ready-to-implement 表示设计已相对明确，可以开始写代码 PR。
贡献者可以认领带标签的 issue。

这个流程适合大型开源项目。它把“想法”“设计”“实现”拆开，减少贡献者一上来就写错方向的风险。

对 AI agent 来说，这也很适合。agent 可以先整理 issue、写 spec、补测试，再进入实现。Warp 自己也在用这种方式展示 agentic project management。

许可：MIT + AGPL v3

Warp 采用双许可结构。

README 说明：

Warp UI framework，也就是 warpui_core 和 warpui crates，使用 MIT license。
仓库其余代码使用 AGPL v3。

这点很重要。AGPL v3 对网络服务和分发有更强的开源要求。如果你只是学习、研究、贡献代码，问题不大；但如果想把 Warp 代码用于商业产品或闭源衍生项目，就必须认真读 license，必要时咨询法律意见。

简单说，Warp 是开源了，但不是“随便拿去闭源商用”的宽松许可。

值得关注的地方

第一，Warp 把终端、agent、项目管理放在一起。

很多 AI coding 工具仍然是 CLI 或编辑器插件。Warp 试图从终端入口出发，把 agent 任务、代码执行、命令输出、PR 工作流和团队协作整合起来。

第二，Warp 的开源方式很适合观察 agent 工作流。

它不只是发布代码，还把贡献概览、agent session、issue triage 和 spec 流程公开出来。对于想研究 AI 如何参与开源协作的人，这个仓库本身就是样本。

第三，Warp 是一个复杂 Rust 桌面应用。

如果你想学习 Rust GUI、终端模拟器、跨平台应用、GraphQL 客户端、云同步和 AI 集成，Warp 仓库有不少可看的结构。但它不是小项目，新贡献者需要先读文档和 issue 流程。

第四，Warp 支持“自带 agent”和“bring your own CLI agent”两条线。

这点很现实。开发者不会只用一个 agent。Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等工具会长期共存。Warp 如果能成为它们的工作台，就比单一终端更有价值。

适合谁关注

如果你是普通终端用户，关注 Warp 的意义在于：终端可能正在从命令行工具变成 AI 工作台。

如果你是 AI coding agent 重度用户，Warp 值得关注，因为它试图管理多个 agent，而不是只做一个聊天入口。

如果你是开源维护者，可以关注 Oz for OSS 这条线。它试图用 agent 做 issue triage、PR review、社区协作和贡献者引导。

如果你是 Rust 开发者，Warp 是一个大型真实桌面应用样本，可以研究它如何组织 UI、终端、云同步、AI 集成和跨平台代码。

如果你只是想找一个能马上替代传统终端的工具，建议先下载正式版使用，再决定是否研究源码。直接从源码构建更适合贡献者和深度玩家。

简短判断

Warp 开源的重点，不只是“一个现代终端开源了”。

更准确地说，Warp 正在把终端升级成 agentic development environment：终端负责连接 shell、代码库、命令执行、agent、issue、PR 和协作流程。

在 AI coding agent 继续增长的背景下，开发环境的入口可能会发生变化。过去是 IDE 统治开发体验，终端负责命令执行；现在终端可能反过来成为 agent 协作的中心。Warp 这个仓库，正是在探索这种可能性。

编译 UEFI 程序入门：从 uefi-simple 到第一个 .EFI

Thu, 30 Apr 2026 19:53:08 +0800

编译第一个 UEFI 程序并不轻松：环境安装耗时，链接器报错很多，.EFI 程序也不像普通桌面程序那样有成熟直观的编辑和运行体验。

这篇就按入门角度整理一下：如果只是想先编译出自己的第一个 UEFI 程序，应该从哪里开始，哪些概念要先搞清楚，哪些坑最容易遇到。

UEFI 程序是什么

UEFI 程序通常是一个 .EFI 文件。

它不是 Windows 下双击运行的普通 .exe，而是运行在 UEFI 固件环境里的 PE/COFF 可执行文件。常见场景包括：

启动管理器
硬件初始化工具
固件更新工具
引导前诊断工具
自定义启动流程

你在系统启动早期看到的很多功能，本质上都可能和 UEFI 应用、驱动或固件服务有关。

对初学者来说，先不用急着理解完整固件开发。第一步只要完成一个目标：编译出一个能被 UEFI Shell 或模拟器加载的 .EFI 文件。

为什么不建议一开始就上 EDK II

UEFI 正式开发经常会遇到 EDK II。

EDK II 功能完整，也更接近真实固件工程，但它对新手不太友好：

工程结构复杂
构建系统有学习成本
环境变量和工具链配置比较多
编译报错不容易看懂
很容易还没写代码，就先卡在环境上

如果目标只是“先跑起来一个最小 UEFI 程序”，更适合从轻量示例开始。

pbatard/uefi-simple 就是这类项目。它的定位很直接：提供一个简单的 UEFI Hello World 示例，让你先把 .EFI 编译出来。

`uefi-simple` 适合用来做什么

uefi-simple 适合做 UEFI 入门的第一块踏板。

它主要解决三个问题：

给你一个最小可编译的 UEFI 应用结构
帮你避开一开始就接触大型固件工程的复杂度
让你能先验证编译、链接、运行链路是否通

这个项目支持不同构建方式，包括 Visual Studio 2022 和 MinGW/gcc，也可以配合 QEMU 与 OVMF 做测试。

也就是说，你不一定非要准备真实机器反复重启测试。先用模拟器把程序跑起来，会安全很多。

入门前要准备哪些东西

最少需要准备几类工具。

第一类是编译工具链。

如果你在 Windows 上，可以优先考虑：

Visual Studio 2022
或 MinGW/gcc

第二类是 UEFI 运行环境。

可以有两种选择：

用真实机器的 UEFI Shell 运行 .EFI
用 QEMU + OVMF 在虚拟环境里测试

第三类是示例项目。

新手不建议从空目录开始手写构建脚本。直接使用 uefi-simple 这类最小示例，可以少踩很多构建系统的坑。

大致流程

一个最小 UEFI 程序的入门流程可以这样理解。

第一步，拿到示例项目。

`1`	`git clone https://github.com/pbatard/uefi-simple.git`

第二步，选择构建工具链。

如果用 Visual Studio，就按项目里的 Visual Studio 方案构建。
如果用 MinGW/gcc，就按项目提供的 Makefile 或说明走。

第三步，生成 .EFI 文件。

这里最关键的是确认目标架构。常见 PC 一般是 x86_64，也就是 64 位 UEFI 环境。

第四步，把 .EFI 放到可以被 UEFI Shell 访问的位置。

如果用真实机器，通常会准备一个 FAT32 分区或 U 盘。
如果用 QEMU，可以把目录或镜像挂载进去。

第五步，在 UEFI Shell 里运行。

运行效果通常就是一个最小输出，比如打印类似 Hello World 的内容。

最容易卡住的地方

编译 UEFI 程序最容易卡的不是 C 语言本身，而是环境和链接。

常见问题包括：

编译器架构不对
目标格式不对
链接参数不完整
缺少 UEFI 入口点
生成的是普通可执行文件，不是 UEFI 能加载的 .EFI
QEMU 或 OVMF 没配置好
真实机器 Secure Boot 阻止运行未签名程序

尤其是链接器报错，经常会让新手误以为代码写错了。
实际上，很多时候是入口函数、子系统、目标架构或链接脚本配置不对。

所以第一阶段不要急着改复杂逻辑。先确保原始示例能编译、能运行，再一点点改输出内容。

测试时为什么推荐 QEMU + OVMF

真实机器测试 UEFI 程序并不是不行，但新手阶段不太方便。

因为你可能需要反复：

编译
拷贝到 U 盘
重启
进入 UEFI Shell
运行
记录报错
回到系统修改

这个循环很慢。

QEMU + OVMF 的好处是可以在操作系统里直接模拟 UEFI 环境。你可以更快地验证 .EFI 是否能被加载，也不容易影响真实机器启动项。

等程序基本跑通，再放到真实机器上测试，会更稳。

新手应该先改哪里

如果你已经用示例项目编译出了第一个 .EFI，下一步不要马上写复杂功能。

建议按这个顺序改：

先改输出文本，确认重新编译后的程序确实生效。
再尝试读取 UEFI 提供的简单信息。
再理解入口函数、输出协议和基本服务。
最后再考虑文件系统、图形输出、启动项管理等复杂功能。

这样做的好处是每一步都能验证。
如果一上来就改很多东西，出错时很难判断到底是代码问题、编译问题，还是运行环境问题。

和普通 C 程序有什么不同

UEFI 程序虽然可以用 C 写，但它和普通 C 程序的运行环境完全不同。

普通 C 程序通常运行在操作系统里，可以依赖标准库、文件系统、进程模型和系统调用。

UEFI 程序运行在操作系统启动之前，它依赖的是 UEFI 固件提供的服务。很多你在普通程序里习惯使用的东西，在这里并不是天然可用。

所以写 UEFI 程序时，要先适应几个变化：

入口函数不一样
输出方式不一样
可用库不一样
内存和文件访问方式不一样
调试方式不一样

这也是为什么推荐先从最小示例开始，而不是直接照普通 C 程序的习惯写。

一个比较现实的学习路线

如果只是入门，可以按这个路线走：

第一步：编译 uefi-simple
第二步：用 QEMU + OVMF 跑起来
第三步：修改 Hello World 输出
第四步：理解 UEFI Shell 怎么加载 .EFI
第五步：学习 UEFI 的入口函数和基本输出协议
第六步：再看 EDK II 或更完整的 UEFI 开发资料

这条路线的重点是先让反馈闭环跑起来。

只要你能从源码生成 .EFI，再在 UEFI 环境里看到输出，就已经跨过了最难的第一道门槛。

参考

最后一句

编译第一个 UEFI 程序，难点通常不在“写出一段 C 代码”，而在把工具链、链接格式和运行环境串起来。

先别急着做复杂功能。
从 uefi-simple 这种最小示例开始，先得到一个能运行的 .EFI，再逐步理解 UEFI 的入口、协议和构建方式，会轻松很多。

GoAccess 最新版自编译与使用记录：从源码安装到实时 HTML 报表

Wed, 29 Apr 2026 00:08:00 +0800

时间点按 2026-04-29 整理，当前官方 README 里给出的最新稳定版是 1.10.2。

1. 先装编译依赖

1
2
3

sudo apt-get update
sudo apt-get install -y build-essential wget tar \
  libncurses-dev libmaxminddb-dev libssl-dev zlib1g-dev

2. 下载最新版源码包

cd /usr/local/src
sudo wget https://tar.goaccess.io/goaccess-1.10.2.tar.gz
sudo tar -xzvf goaccess-1.10.2.tar.gz
cd goaccess-1.10.2

3. 配置编译参数

`1`	`sudo ./configure --enable-utf8 --enable-geoip=mmdb --with-zlib`

如果你还想给实时 HTML 报表配 TLS，也可以改成：

`1`	`sudo ./configure --enable-utf8 --enable-geoip=mmdb --with-zlib --with-openssl`

4. 编译并安装

1
2

sudo make
sudo make install

5. 确认版本

1
2

goaccess --version
which goaccess

6. 直接看终端报表

Nginx 或 Apache 常见 combined 日志可以先这样跑：

`1`	`goaccess /var/log/nginx/access.log --log-format=COMBINED`

如果日志路径是 Apache：

`1`	`goaccess /var/log/apache2/access.log --log-format=COMBINED`

7. 生成静态 HTML 报表

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html

输出到当前目录也可以：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o report.html

8. 生成实时 HTML 报表

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html

如果要改端口：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html \
  --port=7891

如果只绑定本机：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html \
  --addr=127.0.0.1

9. 持续追日志

`1`	`tail -f /var/log/nginx/access.log \| goaccess --log-format=COMBINED -`

从文件开头开始并保持实时：

tail -f -n +0 /var/log/nginx/access.log | goaccess \
  --log-format=COMBINED \
  -o report.html \
  --real-time-html -

10. 只看某类请求

例如只看带 firefox 的请求：

1
2

tail -f /var/log/nginx/access.log | grep -i --line-buffered 'firefox' | goaccess \
  --log-format=COMBINED -

例如只看 5xx 和 3xx：

1
2
3

tail -f -n +0 /var/log/nginx/access.log | awk '$9~/3[0-9]{2}|5[0-9]{2}/' | goaccess \
  --log-format=COMBINED \
  -o out.html -

11. 多个日志一起分析

`1`	`goaccess /var/log/nginx/access.log /var/log/nginx/access.log.1 --log-format=COMBINED`

压缩和未压缩一起读：

`1`	`zcat --force /var/log/nginx/access.log* \| goaccess --log-format=COMBINED -`

12. 开多线程

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.html \
  -j 4

加大 chunk：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.html \
  -j 4 \
  --chunk-size=8192

13. 增量处理

先持久化一份旧日志：

`1`	`goaccess /var/log/nginx/access.log.1 --log-format=COMBINED --persist`

再追加当前日志：

`1`	`goaccess /var/log/nginx/access.log --log-format=COMBINED --restore --persist`

只读取已持久化数据：

`1`	`goaccess --restore`

14. 我自己会先跑的一组命令

sudo apt-get update
sudo apt-get install -y build-essential wget tar \
  libncurses-dev libmaxminddb-dev libssl-dev zlib1g-dev

cd /usr/local/src
sudo wget https://tar.goaccess.io/goaccess-1.10.2.tar.gz
sudo tar -xzvf goaccess-1.10.2.tar.gz
cd goaccess-1.10.2
sudo ./configure --enable-utf8 --enable-geoip=mmdb --with-zlib --with-openssl
sudo make
sudo make install

goaccess --version

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html

就这样。
如果你的目标很明确，其实只要把最新版源码编译好，再把 --log-format=COMBINED 和 --real-time-html 这两个参数先跑通，后面基本就是围着日志路径、输出文件和端口在改。

2026 年嵌入式开发环境怎么选：Keil、STM32CubeIDE、VS Code 与 AI 协作

Wed, 22 Apr 2026 23:05:00 +0800

只要你还在做单片机或者嵌入式开发，很快就会遇到一个很现实的问题：到了 2026 年，在 AI 写代码已经越来越普遍的情况下，开发环境到底应该怎么选？

这个问题表面上像是在比较几个 IDE，实际讨论的却是另一件事：你到底是要一个“能把工程跑起来的工具”，还是一套“兼顾生态、编码体验和 AI 协作能力”的工作流。

如果按这个角度去看，答案往往就不是简单地在 Keil、STM32CubeIDE、VS Code、CLion 里选一个，而是重新组合它们各自最擅长的部分。

先看几个主流选项，各自解决什么问题

嵌入式领域这些年常见的环境，基本还是那几类：

Keil
STM32CubeIDE
VS Code
CLion

如果再往前追，当然还会有人提 IAR。只是从今天的讨论出发，更值得看的已经不是“谁资格最老”，而是谁更适合当前这套开发现实。

Keil：生态强、上手稳，但编辑体验已经明显落后

Keil 到今天仍然很难绕开，原因不复杂：它用得实在太广了。

无论是公司里留下来的老工程，还是网上大量教程、资料、示例工程，很多都还是围绕 Keil 组织的。它在编译、下载、调试这一整套流程上依然成熟，尤其是你真的要把板子跑起来时，它的路径非常短。

它的问题也同样明显：

界面老
编辑体验一般
不擅长承担 AI 辅助编码的主场

所以 Keil 更像是一个“工程入口和调试底座”，而不是一个面向 2026 年编码体验的理想编辑环境。

STM32CubeIDE：对 STM32 友好，但更多是学习和快速起步工具

如果你主要在 STM32 生态里活动，STM32CubeIDE 很容易成为第一个接触到的环境。

它的优点很明确：

上手友好
外设配置和工程生成方便
调试链路相对完整

对学生、新手和刚起步的项目来说，这套体验确实足够直接。

但一旦进入更长期、更多协作、更多定制的工程环境，它的局限也会慢慢暴露出来。尤其是在商业项目或者更复杂的团队工作流里，它未必是那个最舒服的主环境。

所以它更适合“快速启动”和“STM32 生态内的一体化体验”，不一定适合作为长期主力编辑器。

VS Code：严格说不是 IDE，但在 AI 时代优势越来越明显

VS Code 严格来说并不是传统意义上的 IDE，更准确地说，它是一个可扩展的代码编辑器。

这也意味着它天然有两面性。

它的弱点是：

需要插件和配置
对新手不够友好
不能开箱即用地替代嵌入式 IDE 全流程

但它真正强的地方，恰恰也在这里：

可扩展性强
编码体验明显更现代
语法高亮、跳转、搜索、重构体验更好
对 AI 工具和 Agent 工作流支持更积极

在今天这个阶段，很多人真正需要的已经不只是“能写代码”，而是“写代码时能不能顺手把 AI 协作接进来”。从这个角度看，VS Code 的优势几乎是肉眼可见的。

CLion：体验不错，但在嵌入式场景里不够主流

CLion 经常会被提到，因为它的 C/C++ 编码体验一直不差。

但对很多嵌入式开发者来说，它的问题不一定出在“好不好用”，而是“值不值得切过去”：

用的人相对少
与现有嵌入式工程生态连接不如 Keil 直接
在 AI 协作这件事上，也未必比 VS Code 更有现实优势

所以它更像是一个“理论上也能做得不错”的选项，但在今天的嵌入式主流工作流里，并不是最自然的那个核心。

更现实的答案：Keil 负责编译调试，VS Code 负责写代码

如果把上面这些工具拆开看，很容易得到一个更务实的结论：

用 Keil 保留现有工程生态、编译、下载和调试能力
用 VS Code 承担日常编码、搜索、跳转和 AI 协作

这套组合的价值在于，它不是试图用一个工具包打天下，而是让每个工具回到自己最擅长的位置。

对很多嵌入式工程来说，Keil 的生态根本绕不开。既然如此，与其强行把所有工作都塞回 Keil，不如承认它更适合作为后端编译调试入口；而真正的编辑体验，则交给 VS Code。

为什么这套组合在 AI 时代更有优势

到了今天，开发环境的分界线已经不只是“编辑器顺不顺手”，而是“它能不能自然接入 AI”。

VS Code 在这件事上有几个很现实的优势：

AI 插件和 Agent 支持更活跃
代码浏览体验更适合让 AI 读工程、改工程
更容易和现代插件生态结合

这意味着你可以把嵌入式开发里最痛苦的一部分工作，开始交给 AI 帮你分担：

在现有工程里找函数和调用链
快速生成一段初始化代码
帮你补一个串口打印
解释旧工程结构
在已有文件里做小范围修改

这些事情过去不是不能做，而是做起来不顺。VS Code 的意义不只是“更好看”，而是它更容易成为 AI 协作的工作台。

关键补丁：用插件把 VS Code 和 Keil 工程接起来

这套工作流能不能成立，核心不在口号，而在你能不能把 VS Code 和 Keil 工程接起来。

比较实用的一类插件思路，是让 VS Code 直接读取 Keil 工程结构，并在编辑器内部调用 Keil 后台程序完成：

打开工程
编译
下载

这样一来，你日常写代码不用频繁在两个界面之间来回切，只有到了更重的调试环节，再回到 Keil 里做单步、断点和寄存器观察。

这类插件真正有价值的地方，不只是“少切几个窗口”，而是它让工作流连续起来了。

不要忽视 C/C++ 基础插件配置

如果你打算把 VS Code 当作嵌入式主编辑器，一个非常基础但常被忽略的点是：一定要把 C/C++ 基础插件和工程索引配置好。

否则你会遇到一系列很影响体验的问题：

跳转不到定义
红线误报
补全不准
头文件关系混乱

很多人会误以为是 VS Code 不适合嵌入式，实际上往往只是工程索引和插件配置没接好。

一旦这部分配置完整，VS Code 才能真正发挥出它在阅读大型工程、搜索符号、配合 AI 辅助修改代码上的优势。

这套工作流最适合谁

我觉得下面这几类人，会特别适合这种组合式环境：

1. 已经有大量 Keil 工程的人

如果你公司项目、课程资料或者历史代码都围绕 Keil 展开，那就没必要为了“现代化”硬切掉原有生态。保留 Keil，再补一个 VS Code 前端，是迁移成本最低的做法。

2. 想用 AI 辅助写嵌入式代码的人

如果你已经习惯让 AI 帮你解释函数、补样板代码、改局部逻辑，那么 VS Code 会比传统嵌入式 IDE 更自然地承接这件事。

3. 想同时兼顾学习资料和真实项目的人

很多学习资料仍然建立在 Keil 上，但你自己的工作流未必要停留在那个年代。把 Keil 作为工程兼容层，把 VS Code 作为生产力层，会更平衡。

结语

到了 2026 年，嵌入式开发环境的关键问题，已经不再只是“哪个 IDE 功能更多”，而是“哪种组合最符合今天的工作方式”。

如果你只想快速起步，STM32CubeIDE 依然有它的位置；如果你要稳定接住大量既有工程，Keil 依然绕不开；但如果你还想把现代编辑体验和 AI 协作一起接进来，那么更现实的答案，往往是：

Keil 负责编译和调试，VS Code 负责写代码。

这不一定是唯一答案，但很可能是当下最不拧巴的一种答案。

8 种常见配置文件格式怎么选：INI、XML、JSON、YAML、TOML 到 Markdown

Wed, 22 Apr 2026 21:48:37 +0800

只要你经常写代码、折腾服务器、改游戏参数，或者维护各种工具链，基本都逃不过配置文件。

很多时候，真正把程序搞炸的不是算法，也不是框架，而是一行不起眼的配置：少了一个空格、多了一个逗号，或者某个值写成了系统不想看到的样子。把常见配置文件格式放在一起看，很自然会回到几个核心问题：

哪些格式更适合人来写
哪些格式更适合机器来读
在 AI Agent 时代，配置文件这件事会不会发生变化

这篇文章就是围绕这个问题做的一次简洁整理。

01 配置文件，本质上是在协调“人”和“机器”

有个说法我觉得很准确：配置文件其实就是人和程序之间签下的一份“行为契约”。

它的价值很明显。你不需要重写业务代码，也不用重新编译，只改几行文本，就能改变网站行为、应用逻辑、部署方式，甚至游戏画质和隐藏选项。

问题在于，这份契约天然存在矛盾。

从人的角度，我们想要的是：

好看、好写、层级清晰
最好支持注释，方便自己和别人回来看
能少写就少写，最好还能复用和模块化
写错时别一碰就炸

但从机器的角度，它并不关心优不优雅，只关心两件事：

解析要快
规则要严，类型要清楚，最好没有歧义

这就是为什么配置文件格式总是在“人类友好”和“机器友好”之间拉扯。越适合人阅读的格式，机器往往解析更麻烦；越适合机器高效处理的格式，人写起来通常越容易崩溃。

02 INI：简单直白，但能力有限

先从 INI 说起。

它的优点非常直接：

结构简单
分区加键值对，几乎一眼就能看懂
支持注释
很适合一些轻量配置场景，比如游戏参数微调、基础环境设置

如果你改过老游戏配置，或者手动调过一些工具参数，基本都见过它。

但 INI 的问题也很明显。它的结构太扁平，原生不适合表达复杂嵌套和数组。再加上它通常缺少严格的类型系统，很多值本质上就是一串文本，最终怎么解释，要靠程序自己处理。

所以 INI 更像是一台老式但顺手的工具车，轻活很好用，复杂项目就容易力不从心。

例如一个很典型的 INI 配置会长这样：

[server]
host=127.0.0.1
port=8080

[feature]
enable_cache=true

03 XML：严谨、稳定，但写起来很累

第二位是 XML。

如果你维护过老 Java 项目，或者见过一大堆成对闭合标签的配置文件，对它应该不陌生。

XML 的优点是：

层级结构明确
支持注释
规则严整
可以配合 schema 做强校验

这意味着机器在正式读取前，就能先知道字段类型、出现次数和结构约束，安全感很高。

但它对人的折磨也很经典：

标签冗长
视觉噪音很大
文件容易膨胀
稍微漏一个闭合标签，就可能整页报错

所以 XML 非常像一份盖章齐全的正式合同。机器喜欢，人工维护 often 很累。如今很多新项目已经不再优先选它，但在一些老系统和严规则场景里，它依然没有完全退场。

同样的配置如果写成 XML，大概会是这样：

<config>
  <server>
    <host>127.0.0.1</host>
    <port>8080</port>
  </server>
  <feature>
    <enable_cache>true</enable_cache>
  </feature>
</config>

04 JSON：数据交换霸主，但不适合手写复杂配置

说到现代开发，JSON 几乎绕不过去。

对 JSON 来说，一个很典型的判断是：作为数据交换格式，它非常强；但作为人工维护的配置文件，它有点别扭。

它的优势包括：

对象和数组结构清晰
网络传输友好
解析器成熟
对 Web API 和前后端通信非常合适

尤其和 XML 放在一起时，JSON 的轻量优势会非常明显。同样的数据结构，JSON 通常更短，也更适合在网络里传来传去。

但它有个致命缺点：标准 JSON 不支持注释。

另外，它的语法也比较严格：

key 必须带双引号
最后一项后面不能多逗号
少一个符号就会直接报错

所以 JSON 很适合 API、服务之间的数据交换，却不总是适合手动维护、需要写说明、需要频繁修改的配置文件。

比如：

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  },
  "feature": {
    "enable_cache": true
  }
}

05 YAML：可读性很强，但缩进和隐式类型会坑你

如果你碰过 Docker、CI/CD、Kubernetes、自动化部署，基本一定和 YAML 打过交道。

它最吸引人的地方，就是看起来很“干净”：

少了很多大括号和引号
用缩进表达层级
支持注释
还能做锚点复用

所以从人的第一眼体验来说，YAML 通常比 JSON 友好得多。

但问题也正出在这里。它把很多复杂性藏起来了，实际使用时经常出现两类经典事故：

缩进地狱
隐式类型转换

缩进问题很好理解，空格多一个少一个，配置就可能直接坏掉。更麻烦的是隐式类型转换，比如某些看起来像普通字符串的值，可能会被自动解释成布尔值或别的类型。

这也是为什么很多人一边夸 YAML 好看，一边又被它折腾得很惨。它在人类阅读体验上确实很好，但机器解析它时并不轻松，而且不同解析库之间还可能有细微差异。

同样的配置写成 YAML，通常会更清爽：

server:
  host: 127.0.0.1
  port: 8080

feature:
  enable_cache: true

06 TOML：在可读性和确定性之间找平衡

TOML 经常被放在“当代均衡答案”的位置上。

TOML 的好处在于，它有点像把 INI 的直观和 JSON 的类型明确结合在一起：

支持注释
结构清楚
强类型更明确
日期时间等常见类型支持更自然
不容易出现 YAML 那种隐式转换坑

尤其在现代工具链里，TOML 已经越来越常见，比如 Python 的 pyproject.toml。

当然它也不是没有缺点。对于很深层的嵌套结构，TOML 会显得有点啰嗦，路径式书写写多了会烦。但如果场景是中小型项目配置、工具配置、包管理配置，TOML 的整体体验往往比较稳。

如果你想找一种“注释有、语义清、机器也不难受”的格式，TOML 确实值得优先考虑。

一个常见的 TOML 写法会像这样：

[server]
host = "127.0.0.1"
port = 8080

[feature]
enable_cache = true

07 `.conf` 和 Apache 配置：不是通用格式，而是领域语法

有一点很值得提醒：很多人看到 .conf，会误以为它是一种统一格式，其实不是。

.conf 只是“configuration”的后缀名，里面到底怎么写，完全看具体系统自己的规则。也就是说，.conf 更像一个大类，不是一套标准语法。

拿 Apache 配置举例，它的配置方式很有代表性：

一部分像单行指令
一部分又像带作用域的标签结构
很适合 Web 服务器这种特定领域

优点是对运维场景很顺手，表达权限、路由、虚拟主机这类规则比较自然；问题是它几乎只服务于自己的生态，不具备很强的通用性。

所以这类配置更像“领域专用语言”，在特定系统里很好用，但不适合拿来当通用配置格式看待。

例如一个极简的 Apache 风格配置，会更像一组指令：

Listen 80

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/var/www/html"
</VirtualHost>

08 Protocol Buffers：工业级强类型方案，但门槛高

Protocol Buffers 其实已经不是传统意义上的“随手写个配置文件”了，而更像一套正式的数据定义和序列化方案。

它的优势很强：

强类型
schema 明确
向前向后兼容性好
二进制传输体积小
机器处理效率很高

但代价也很明显：

需要先写 .proto
需要工具链和编译步骤
对小项目来说门槛偏高

所以它不适合“我就配个小工具”的轻量场景，但如果你是在做大型系统、RPC、分布式服务或者长期演进的数据协议，它会比很多轻量配置格式更可靠。

它的写法更接近“先定义结构，再生成代码”：

syntax = "proto3";

message ServerConfig {
  string host = 1;
  int32 port = 2;
  bool enable_cache = 3;
}

09 在 AI Agent 时代，Markdown 可能重新变成“配置方式”

最有意思的部分，是把 Markdown 也算进了“配置文件”的讨论里。

这在传统程序视角里听起来有点奇怪，因为 Markdown 本来更像文档格式。但如果把对象换成大语言模型和 AI Agent，这个判断其实是成立的。

为什么？

因为传统程序依赖的是严格语法和固定字段，而大模型更擅长理解语义、结构和上下文。对于它们来说：

标题就是层级
列表就是步骤
加粗就是强调
自然语言本身就能承载规则

也就是说，当配置对象从“死板的解析器”变成“能读懂语义的 Agent”，Markdown 这类人类友好的结构化文本，反而可能成为一种更自然的配置形式。

这也是一个很关键的判断：在传统软件时代，很多配置格式是为了让人去适应机器；而在 AI 时代，机器开始反过来适应人的表达。

比如给 Agent 写任务配置，完全可能直接写成这样：

# 任务目标

为新用户写一封欢迎邮件。

## 要求

- 语气友好
- 不超过 150 字
- 提到产品的 3 个核心功能

## 禁止事项

- 不要承诺不存在的功能
- 不要使用夸张营销语气

10 到底该怎么选

如果把这些观点压缩一下，我觉得可以简单分成这样几类：

想要极简、轻量、扁平配置：INI
想要强结构、强校验、老系统兼容：XML
想要网络传输和接口交换：JSON
想要高可读性、云原生和部署配置：YAML
想要更稳的现代通用配置体验：TOML
想要特定系统内部规则：.conf / Apache 一类 DSL
想要工业级协议和长期演进能力：Protocol Buffers
面向 AI Agent 的自然表达和任务编排：Markdown

所以“最好的配置文件格式”其实并不存在。它取决于你是在为谁写：

为人维护
为机器高速解析
为服务之间通信
还是为 AI Agent 理解和执行

简单总结

配置文件的发展史，本质上就是人和机器不断重新分配理解成本的过程。

过去是人迁就机器，所以我们要记各种括号、缩进、引号和严格规则。现在随着大语言模型和 Agent 系统越来越成熟，机器开始更能理解自然表达，于是“配置”这件事本身也在变化。

也许未来很多场景里，配置文件不再是某种固定格式，而更像一段结构化意图说明。而在那之前，JSON、YAML、TOML、INI、XML 这些格式依然会长期共存，各自占据最适合自己的位置。

Windows 上在 VS Code 里构建 Docker 镜像：从环境准备到一键构建

Thu, 16 Apr 2026 10:20:00 +0800

如果你想在 Windows 上直接用 VS Code 管理并构建 Docker 镜像，流程其实很短。核心就是三步：先把环境装好，再准备 Dockerfile，最后执行构建。

01 前置准备

先确认两项基础条件：

安装并启动 Docker Desktop。
在 VS Code 里安装 Microsoft 官方 Docker 扩展。

在 Windows 上，建议把 Docker Desktop 切到 WSL 2 后端（Settings > Resources > WSL Integration），一般会更稳定、性能也更好。

02 准备 Dockerfile

如果项目里还没有 Dockerfile，可以直接让 VS Code 生成：

在 VS Code 打开你的项目目录。
按 F1 或 Ctrl+Shift+P 打开命令面板。
运行 Docker: Add Docker Files to Workspace。
选择你的平台（例如 Node.js、Python、.NET），按提示完成。

执行后通常会得到至少两个文件：

Dockerfile
.dockerignore

这一步的价值是先有一个可工作的基础版本，后面再按项目需求微调。

03 构建镜像的三种方式

方式 A：右键 Dockerfile

在资源管理器中右键 Dockerfile，选择 Build Image...，然后输入镜像标签（tag）。

方式 B：命令面板

按 F1 运行 Docker: Build Image，再按提示选择上下文和标签。

方式 C：集成终端命令

`1`	`docker build -t your-image-name .`

这条命令表示用当前目录作为构建上下文，生成名为 your-image-name 的镜像。

04 常见问题快速检查

Docker Desktop 没启动：先确认托盘图标显示为运行状态。
构建很慢：优先检查是否启用 WSL 2 后端。
构建失败提示找不到文件：确认执行目录是项目根目录，且 Dockerfile 在上下文内。
扩展看不到 Docker 资源：重启一次 VS Code，或确认 Docker CLI 可用（docker version）。

小结

在 Windows 上用 VS Code 构建 Docker 镜像并不复杂。先安装 Docker Desktop 和 Docker 扩展，再用命令面板生成 Dockerfile，最后用右键或 docker build 即可完成日常构建流程。

CH347 开发常用资源整理：驱动、工具与 SPI Flash 刷写

Fri, 03 Apr 2026 10:00:00 +0800

这篇文章整理我在使用 CH347 时最常用的一组资源，目标是开箱就能开始调试和刷写。

如果你刚接触 CH347，建议按下面顺序准备环境：

先看官方产品页确认资料入口
按用途安装对应驱动
准备 SPI Flash 刷写工具并做连通性验证

官方入口

CH347 产品页：https://www.wch.cn/products/CH347.html

建议优先从官方页面进入下载区，避免拿到来源不明或版本过旧的驱动包。

常用驱动

1) `CH341PAR.EXE`

用途：

USB 转 JTAG / SPI / I2C / 并口 / GPIO 等接口驱动

适用场景：

你需要用 CH347 做多协议通信或底层接口调试时

2) `CH343SER.EXE`

用途：

USB 转高速串口 Windows 厂商驱动

适用场景：

主要把 CH347 当串口工具使用，且需要较高串口速率时

SPI Flash 刷写工具

AsProgrammer：https://github.com/nofeletru/UsbAsp-flash

常见用途：

识别 SPI NOR Flash
读取芯片 ID
备份原始固件
擦除/写入/校验固件

FFmpeg 的 `-map` 参数详解：精准选择视频、音频与字幕流

Thu, 02 Apr 2026 23:14:03 +0800

在多音轨、多字幕的视频处理中，-map 是 FFmpeg 最关键也最容易用错的参数之一。

如果你不显式指定 -map，FFmpeg 会按默认规则自动挑选流，结果常常不是你想要的。比如：

导出后丢了字幕
选错了音轨语言
混入了不需要的数据流

这篇文章用最常见的场景，讲清楚 -map 怎么用。

先理解什么是“流”

一个容器文件（例如 mp4、mkv）里通常不止一个内容流（stream），常见包括：

视频流（v）
音频流（a）
字幕流（s）
附件/数据流（如字体、封面、章节等）

你可以先用 ffprobe 看清文件里有什么流：

`1`	`ffprobe -hide_banner input.mkv`

`-map` 的基本语法

最常见写法：

`1`	`-map input_index[:stream_type][:stream_index]`

例如：

0:v：第 1 个输入文件的所有视频流
0:a:0：第 1 个输入文件的第 1 条音频流
1:s:1：第 2 个输入文件的第 2 条字幕流

说明：

input_index 从 0 开始，对应 -i 的顺序
stream_index 也从 0 开始

实战示例

1) 视频来自 A，音频来自 B

ffmpeg -i english.mp4 -i french.mp3 \
  -map 0:v:0 -map 1:a:0 \
  -c:v copy -c:a aac \
  french.mp4

含义：

取 english.mp4 的第 1 条视频流
取 french.mp3 的第 1 条音频流
合并输出为 french.mp4

2) 保留第一个输入的全部流，再额外加一条音轨

ffmpeg -i english.mp4 -i french.mp3 \
  -map 0 -map 1:a:0 \
  -c copy \
  english-french.mp4

含义：

-map 0 先把第一个输入文件中的所有流都带上
再追加第二个输入的第 1 条音频流

两个很实用的进阶技巧

1) 负映射：排除不想要的流

例如保留第一个输入的全部流，但去掉第 2 条音频流：

`1`	`ffmpeg -i input.mkv -map 0 -map -0:a:1 -c copy output.mkv`

2) 可选映射：流不存在也不中断

某些文件可能没有字幕，这时可以用 ?：

`1`	`ffmpeg -i input.mp4 -map 0:v -map 0:a -map 0:s? -c copy output.mp4`

0:s? 表示“有字幕就映射，没有就跳过，不报错”。

常见坑位

-map 一旦使用，FFmpeg 就不再按默认自动选流，必须把你要的都写出来。
-c copy 只是封装复制，不做转码；若目标容器不支持某编码，仍会失败。
多输入时最容易错的是输入序号，记住序号只看 -i 的先后顺序。
想做稳定脚本时，先 ffprobe 再生成 -map，比手写更稳。

总结

-map 的核心就是一句话：明确告诉 FFmpeg，“从哪个输入，拿哪类流，拿第几条”。

掌握它之后，你就能稳定处理多音轨、多字幕、跨文件拼接等复杂场景，避免“导出结果不对但又不知道为什么”的问题。

如何排查由插件引起的 VS Code CPU 占用过高

Wed, 01 Apr 2026 00:00:00 +0000

VS Code 突然变卡、风扇狂转、CPU 长时间高占用时，最常见原因通常不是编辑器本体，而是扩展插件冲突或插件行为异常。

这篇文章给你一套可以立即执行的排查路径，优先用最省时间的方法定位问题。

先做最快的定位：Start Extension Bisect

Start Extension Bisect 的核心思路是二分法：每一轮临时禁用一半扩展并重启，通过你反馈“问题是否仍存在”，快速缩小范围，直到定位到可疑插件。

操作步骤：

按 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）打开命令面板。
输入并执行 Start Extension Bisect。
每次重启后观察 CPU 占用和卡顿是否复现。
重复几轮后，VS Code 会给出可疑扩展列表。

定位后怎么处理

找到可疑插件后，建议按这个顺序处理：

先更新插件到最新版本。
若无改善，临时禁用该插件 1-2 天观察。
对于功能可替代的插件，优先换成更轻量方案。
若必须使用该插件，检查它的高级配置，关闭不必要的实时分析、索引或监听功能。

两个容易被忽略的“放大器”

即使主因是插件，以下配置也会放大 CPU 问题：

搜索范围过大
例如把构建产物、依赖目录、日志目录也纳入全局搜索，会让插件和文件索引持续高负载。
文件监控包含大目录或软链接
软链接、缓存目录、自动生成目录容易触发大量文件事件，导致扩展反复工作。

可以在 settings.json 中适当排除目录，例如：

{
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/build": true
  },
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/node_modules/**": true,
    "**/dist/**": true
  }
}

复盘建议

如果你已经定位到问题插件，建议记录三件事：插件名称、触发场景、最终处理方式。
这样下次迁移环境或重装系统时，可以快速避开同类问题。

总结

VS Code 高 CPU 占用的排查，最有效路径是先用 Start Extension Bisect 快速定位，再结合搜索和文件监控范围做收敛。
先定位，再优化，比“盲目禁用一堆插件”更省时间，也更稳定。