Blog on Kmoon Blog

QUERY：全新的 HTTP 请求方法

hushan@kmoon.fun (Kmoon) — Fri, 26 Jun 2026 13:10:41 +0800

不同 AI Coding Agent 对 Skills 的管理方式

hushan@kmoon.fun (Kmoon) — Mon, 22 Jun 2026 19:57:10 +0800

前两天我在做一个工具，想统计一下自己每天到底调用了多少次 Claude Code 的 skill。

听起来很简单对吧，就是做个上报，记录一下什么时候用了什么 skill，用了几次。但我刚开始写代码就懵了。

Claude Code 的 skill 是本地 Markdown 文件，Cursor IDE 的 skill 藏在设置里的 JSON 配置，Codex CLI 的 skill 是 YAML 格式。我要适配所有 Coding Agent，却发现它们管理 skill 的方式完全是八套不同的逻辑。

不是哥们，我就想记个日志，怎么各家差别能这么大？？？

这件事让我意识到，如果你想做一个通用的 skill 调用上报工具，首先得搞清楚每家 Agent 在三个维度上的差异。

存放路径在哪，怎么加载，以及最关键的，Hook 模型是什么样的。

咱们一个个拆开了聊。

先从 CLI 工具说起。

Claude Code 是最直白的。它就放在项目目录下的 .claude/skills/ 文件夹里，每个 skill 是一个子文件夹，里面必须有一个 skill.md 文件。

这种设计的好处是，skill 就是项目代码的一部分。你把项目仓库 clone 下来，skill 跟着一起下来了，完全不需要额外安装。而且因为就在文件系统里，你想做监控很容易，用文件系统监听或者直接读目录结构都行。

我跟你说，我做上报工具的时候，Claude Code 这块儿是最省心的。直接遍历 .claude/skills/ 目录，解析每个子文件夹里的 skill.md，提取 frontmatter 里的 name 和 description，一个 os.walk 就搞定了。

Codex CLI 是 OpenAI 出的官方 Coding Agent，它的 skill 系统叫 Commands，配置放在 .codex/commands/ 目录下，每个 command 是一个 YAML 文件。

Codex 也支持全局和项目级配置，全局的在 ~/.codex/commands/。Codex 的设计介于 Claude Code 和 Cursor 之间，它用 YAML 而不是 Markdown，保留了一些可读性，同时保持了结构化的优势。每个 command 可以定义参数、描述、还有可选的 hooks，比如在代码提交前自动执行。

然后是 Trae CLI，也叫 CoCo，字节出的命令行工具。

CoCo 的 skill 配置放在 .coco/skills/ 目录，格式是 TOML。TOML 比 JSON 友好，比 YAML 简单，CoCo 选择这个格式是有考量的。而且 CoCo 支持 skill 市场，你可以从远程仓库拉取别人分享的 skill，本地只是一个缓存。

这种设计给上报带来了复杂性，因为 skill 可能来自远程，本地文件只是一个副本，版本可能随时变化。

接下来是 Gemini CLI，Google 的命令行工具。

Gemini CLI 的 skill 系统叫 Code Actions，配置方式很特别，它不是本地文件，而是 Google Cloud 上的资源。你在本地项目里看不到任何 skill 配置文件，所有的 skill 都定义在 Cloud Console 里，通过项目 ID 关联。

这种云原生的设计意味着，做上报工具的时候，你必须调用 Google Cloud API 才能获取 skill 列表，本地文件系统帮不上忙。

好，CLI 说完了，聊聊 IDE。

Cursor IDE 也有 skill 系统，虽然它也在推 MCP，但 Cursor 本身有一套原生的 skill 配置。它的 skill 分为两类，一类是全局 skill，一类是项目级 skill。

全局 skill 的配置存在 ~/.cursor/settings.json 里。项目级 skill 配置在项目根目录的 .cursor/skills.json 里。

注意，Cursor 的 skill 配置是纯 JSON，不像 Claude Code 是 Markdown。每个 skill 有一个 name、description、prompt，还可以定义什么时候触发。这种结构化的好处是解析简单，坏处是可读性差，写 prompt 的时候不能换行、不能用 Markdown 格式，一长串文本挤在 JSON 字符串里，看着头大。

Trae IDE 是字节出的桌面端，它的 skill 系统叫智能体，配置放在 .trae/agents/ 目录下。每个智能体是一个 JSON 文件，但 Trae 的创新点是支持多轮对话模板，你可以定义一个完整的对话流程，而不只是一个静态 prompt。

这种设计让 skill 更像是一个剧本，AI 按照预设的步骤和用户交互。对于我的上报工具来说，这意味着我需要解析更复杂的结构，因为每个 skill 可能包含多个步骤的触发点。

说到 OpenCode，开源社区孵化的 Coding Agent。

OpenCode 的 skill 系统是最激进的，它完全照搬了 Claude Code 的设计，放在 .opencode/skills/ 目录，也是 Markdown 格式。但它加了一个功能叫 skill 继承，一个项目可以继承另一个项目的 skill，形成层级结构。

这意味着 skill 的来源不只是当前项目，可能还有父项目、全局配置。做上报的时候，你得递归解析整个继承链，才能知道最终有哪些 skill 可用。

然后是 OpenClaw，飞书出的 Coding Agent。

OpenClaw 的 skill 配置放在 .openclaw/skills/ 目录，格式是 JSON。但 OpenClaw 的特殊之处在于它和飞书生态深度绑定，skill 可以通过飞书多维表格来管理，本地文件只是同步下来的缓存。

这种设计对上报工具很不友好，因为 skill 的真相在云端，本地文件可能过期，也可能被手动修改后还没同步。

说到这儿，你可能会发现一个问题。

CLI 和 IDE 在 skill 存放路径上有个本质区别。CLI 工具基本都是项目级配置，skill 文件就在项目里，跟着代码走。IDE 则既有全局配置又有项目级配置，而且往往把配置藏在用户目录或者云端。

这个区别对上报工具的影响很大。CLI 工具的上报可以基于文件系统监听，IDE 的上报则需要同时监控多个位置，还要处理合并逻辑。

好，路径聊完了，说说加载方式。

这块儿才是真正考验适配难度的地方。

Claude Code 的加载方式是静态扫描加热重载。启动的时候，它会递归扫描 .claude/skills/ 目录，读取每个 skill.md 文件，解析 YAML frontmatter 和正文内容，然后把这些 skill 注册到内存里。而且支持热重载，你修改了 skill 文件，保存后立刻生效，不需要重启。

对于我的上报工具来说，这意味着我需要监听文件系统变化，持续更新 skill 列表。

Codex CLI 的加载也是静态扫描加热重载，和 Claude Code 类似。但它多了一个条件加载，支持在 command 里定义 when 条件，比如当文件是 Python 时才显示这个 command。这意味着即使扫描到了 skill，也不一定对所有文件都可用。

CoCo 的加载需要区分本地 skill 和远程 skill。本地的是静态扫描，远程的需要调用 API 获取列表，还要处理版本缓存。如果网络不好，CoCo 会回退到本地缓存，这时候上报的数据可能不准确。

Gemini CLI 的加载完全依赖网络，启动时调用 Google Cloud API 获取项目的 Code Actions。如果网络不通，Gemini 就完全没有 skill 可用。这种设计对上报工具来说，意味着必须处理各种网络异常。

说到 IDE 的加载方式。

Cursor IDE 的加载方式是静态扫描，但它不支持热重载。你修改了 .cursor/skills.json，需要重启 Cursor 才能生效。而且全局 skill 和项目级 skill 是合并加载的，如果有同名 skill，项目级的会覆盖全局的。

这种合并逻辑给上报带来了麻烦，因为你得知道最终生效的是哪个 skill。我的方案是启动时读取全局配置，然后读取项目配置，自己做合并逻辑，和 Cursor 保持一致。

Trae IDE 的加载方式更复杂，因为它支持动态智能体。除了启动时扫描 .trae/agents/，Trae 还可以在对话过程中动态加载新的智能体，基于上下文判断用户需要什么能力。这种动态加载给上报带来了挑战，因为 skill 列表不是固定的。

OpenCode 的加载最复杂，因为要处理 skill 继承链。它需要先加载全局 skill，然后加载父项目的 skill，最后加载当前项目的 skill，每一层都可能覆盖上一层的同名 skill。这个过程是递归的，如果项目嵌套很深，加载时间会很长。

OpenClaw 的加载需要同步飞书云端。启动时会检查本地缓存和云端的版本，如果有更新就下载。这意味着 skill 列表可能随时变化，上报工具需要持续监听同步事件。

说到加载，必须提一嘴 skill 的概念。

Claude Code 支持子 skill，你可以在一个 skill 文件夹里放多个子文件夹，每个子文件夹是一个子 skill。比如 adk-sdd/ 下面有 adk-sdd-plan/、adk-sdd-implement/ 等。它们之间可以互相调用，形成一个完整的工具链。

这种层级结构给上报带来了额外复杂度，因为你得递归扫描子目录，而且子 skill 的调用关系也得记录。

OpenCode 也支持类似的层级结构，而且它还有 skill 继承，复杂度更高。其他 Agent 像 Cursor、Trae、Codex、CoCo 都不支持子 skill，是扁平结构。

好，路径和加载都说完了，最后聊聊 Hook 模型。

这是各家差异最大的部分，也是我做上报工具时最纠结的地方。

Claude Code 的 Hook 模型，我总结为被动触发加语义匹配。你不需要显式调用 skill，Claude Code 会根据对话内容自动判断，把 skill 的 description 和 user message 做语义匹配，超过阈值就注入 prompt。

这种模型的优点是交互自然，缺点是可控性差。做上报的时候，Claude Code 没有官方 Hook 点，我只能通过解析 .claude/logs/ 目录下的日志来间接推断 skill 是否被激活。

Codex CLI 的 Hook 模型是命令式加事件式结合。Commands 可以显式调用，也可以通过定义的 hooks 在特定事件触发，比如 onSave、onCommit。做上报的时候，你需要同时监控用户命令和编辑器事件。

CoCo 的 Hook 模型是关键词触发加场景识别，除了匹配关键词，CoCo 还会分析当前编辑场景，比如你在写测试，它就自动推荐测试相关的 skill。这种模型需要上报工具理解场景是怎么定义的。

Gemini CLI 的 Hook 模型完全是黑盒，因为 skill 在云端，触发逻辑也由服务端控制。本地只能看到最终的 AI 回复，看不到中间过程。做上报基本不可能，除非 Google 开放 API。

说到 IDE 的 Hook 模型。

Cursor IDE 的 Hook 模型是混合触发，可以通过 /skill-name 显式调用，也可以让 AI 自动判断。显式调用容易监控，自动判断就需要解析日志。

Trae IDE 的 Hook 模型是剧本驱动，因为支持多轮对话模板，一个 skill 可能在对话的不同阶段多次触发。比如第一步询问需求，第二步生成代码，第三步解释代码。每个步骤都是一个 Hook 点，上报工具需要追踪整个对话流程。

OpenCode 的 Hook 模型和 Claude Code 类似，也是被动触发。但由于有 skill 继承，触发的时候可能同时激活了父项目和子项目的 skill，上报工具需要记录这个层级关系。

OpenClaw 的 Hook 模型是意图识别加工作流，它会先识别用户意图，然后触发对应的工作流。工作流可能包含多个 skill 的串联调用，上报的时候你需要记录整个调用链。

说了这么多，我来帮你理一理这八家 Agent 的差异。

Agent	类型	路径	格式	加载方式	Hook 模型	上报难度
Claude Code	CLI	`.claude/skills/`	Markdown	静态扫描加热重载	被动触发	中等
Codex CLI	CLI	`.codex/commands/`	YAML	静态加热重载加条件	命令加事件	中等
CoCo	CLI	`.coco/skills/`	TOML	静态加远程	关键词加场景	高
Gemini CLI	CLI	Cloud Console	-	API 获取	黑盒	不可能
Cursor IDE	IDE	`~/.cursor/settings.json`	JSON	静态扫描	混合触发	中等偏高
Trae IDE	IDE	`.trae/agents/`	JSON	静态加动态	剧本驱动	高
OpenCode	IDE	`.opencode/skills/`	Markdown	继承链加载	被动触发	中等偏高
OpenClaw	IDE	`.openclaw/skills/`	JSON	云端同步	意图加工作流	很高

从这张表你能看出什么？

首先，CLI 和 IDE 泾渭分明。CLI 工具普遍使用项目级配置，格式多样，Markdown、YAML、TOML 都有。IDE 则倾向于 JSON 配置，而且普遍有全局加项目级的双层结构。

其次，云原生是趋势。CoCo、Gemini CLI、OpenClaw 都不同程度地依赖云端，本地只是一个视图或缓存。这对上报工具提出了新要求，不能只盯着文件系统，还得调 API、处理网络异常。

最后，Hook 模型越来越复杂。从最简单的显式调用，到被动触发，再到剧本驱动、意图识别，Agent 越来越智能，但也越来越不透明。上报工具能拿到的信息越来越少，很多都是黑盒。

说真的，写到这儿，我突然意识到一个问题。

为什么各家在 skill 管理上差异这么大？

背后其实是产品哲学的不同，CLI 和 IDE 的目标用户不一样，设计思路自然也不同。

Claude Code 和 OpenCode 相信文件即真理。skill 就应该像代码一样，放在版本控制里，任何人都能看、能改、能复现。这种哲学决定了本地优先、透明可见的设计。

Codex CLI 相信配置的标准化。YAML 比 Markdown 结构化，比 JSON 可读性好，是工程化团队的首选。

CoCo 相信生态的力量。skill 不应该绑定在本地，而应该可以分享、可以订阅、可以版本管理。这种设计牺牲了离线可用性，换来了社区活力。

Gemini CLI 相信云服务的整合。skill 是 Google Cloud 生态的一部分，用户不需要关心配置，只需要用。

Cursor IDE 和 Trae IDE 相信配置的灵活性。JSON 虽然难写，但好解析，适合图形化配置界面。而且全局加项目级的双层结构，满足了个人习惯和团队协作的不同需求。

OpenClaw 相信飞书生态的协同。skill 可以通过多维表格管理，非技术人员也能参与配置。

这八种哲学没有对错，只是取舍不同。

但对于我这种想做通用上报工具的人来说，这就很痛苦了。因为没有标准，每家都有自己的玩法，你得为每家写一套适配代码。

我有时候觉得，AI Coding Agent 的发展，就像早期的浏览器大战。Netscape 和 IE 各有各的 DOM API，开发者苦不堪言。直到 W3C 标准化之后才好转。

skill 管理目前还没有统一标准，Markdown、JSON、YAML、TOML 混用，触发模型也五花八门。

短期内，这种碎片化还会继续。

写到这儿，我突然想起我做上报工具的初衷。

我其实只是想知道自己每天用了多少次 skill，哪些 skill 最有用，哪些可能可以删掉。一个简单的数据分析需求，却因为底层差异变得异常复杂。

但换个角度想，这种复杂度本身，就是 AI 工具现状的真实写照。

我们还在早期，还在探索，还在争吵什么是最好的方案。这种混乱是创新的代价，也是进化的必经之路。

或许几年后回头看，今天的这些差异都会显得幼稚。但在当下，我们必须面对它们，理解它们，在碎片中寻找规律。

这就是我这几天做适配的最大感受。

无论你用 Claude Code、Cursor、Trae 还是 Codex，skill 管理的本质问题是一样的，怎么让 AI 学会新能力，怎么让它在合适的时机调用这些能力，怎么让这一切对开发者透明、可控。

每家产品都有自己的答案，而我在这些答案之间，试图搭一座桥。

一文讲清 RAG 效果评测 101

hushan@kmoon.fun (Kmoon) — Sat, 20 Jun 2026 20:26:53 +0800

评估阶段

针对 RAG 的评估主要分为两个阶段的评估：检索阶段、生成阶段。其中检索阶段需要评估召回的文档的相关性，生成阶段需要评估模型生成的内容的正确性。

检索阶段

生成阶段

评估指标

评估框架

luckin CLI：实现在终端里点杯瑞幸咖啡

hushan@kmoon.fun (Kmoon) — Thu, 18 Jun 2026 11:28:59 +0800

上周末加班，今天调休，相当于提前放端午假了哈哈。

瑞幸咖啡太能整活了，听说出了瑞幸咖啡 CLI 服务，可以在终端调用 CLI 服务，让下单更加便捷。刚好前几天女朋友跟我说瑞幸出了一个新品，“弗朗明戈-跳跳冰茶”，说里面有跳跳躺，喝起来很神奇。我们今天就来尝尝看，顺便看看这个 CLI 是整活还是真能用！

首先，访问瑞幸咖啡AI开放平台，可以看到网站做的还是很简洁科技风的。

我们按照官网教程，安装 CLI 工具：

curl -fsSL https://open.lkcoffee.com/install | bash

我们可以看到已经成功安装了 luckin 0.0.1 CLI 工具。接下来我们在终端输入 luckin 回车：

需要先登录授权一下，这里可以看到是跳转到浏览器官网进行授权登录，然后创建一个 Token。

然后我们返回终端，可以看到已经登录成功了，并且可以看到支持哪些斜杠命令：

我们先查看一下附近门店，使用 /store 命令，这里突然离谱了起来，这个命令居然需要我自己输入经纬度？？？

算了，我们还是在 Claude Code 里面使用它的 my-coffee Skill 吧。希望后续可以打通定位服务，自己定位用户所在位置。

我们将官网创建的 Token 手动复制过来，并告诉它在附近帮我点一杯新品冰茶：

这里需要我们扫码支付一下，支付完成后会帮我们查询订单状态和取餐码。这里我们可以发现目前只支持自取，暂时不支持外卖配送。不过我相信不久的将来，当美团 CLI、淘宝闪购 CLI 出现的时候，是完全可以支持外卖配送的。

好啦，现在我们可以准备去门店取餐了。

打开手机的小程序，我们可以看到订单制作完成，等待取餐中：

也是成功喝到新品了，一直滋滋滋，跟小时候吃的跳跳糖一样。

写在最后

这次折腾这么久，最后也确实成功完成了在终端里下单一杯咖啡。瑞幸这次不是简单整活，而是提供了完整的一套 MCP + CLI + Skills，同时也提供了工具文档，这体现了瑞幸选择拥抱 AI 这条路上迈出了第一步。

Google 开源 Agent OKF 新标准

hushan@kmoon.fun (Kmoon) — Wed, 17 Jun 2026 09:34:20 +0800

Reference:

Introducing the Open Knowledge Format

AI 寒武纪：谷歌突然开源Agent OKF新标准！

GitHub：knowledge-catalog

Open Knowledge Format，简称 OKF，6 月 12 日发布，GitHub 仓库三天冲到 3300+ stars。它要做的事情很简单：给 AI 知识库定一个通用的、可移植的格式规范。

为什么需要统一格式

我们平时给 AI 的文档大部分都是内部知识，来源方方面面：数据库表字段含义、接口定义规范、业务功能模块、平台操作手册。这些文档没有统一格式，不同部门关注的重点也不同。这就导致每次新开发一个 Agent，都得从头注入、清洗、梳理一遍知识库。知识没有流通，锁在创建它的那个平台里。

更麻烦的是，每个人搭建知识库的方式都不同。有的全部放在一起靠目录区分模块，有的分模块放在不同知识库；有的用长串文件名标记属性，有的更习惯用 frontmatter。对人类来说这无所谓，自己写的自己找得到。但 Agent 需要的是一份格式稳定的"说明书"，不是每次都重新学习你的目录组织习惯。

OKF 是什么

核心设计很简单：一个 OKF bundle 就是一个 Markdown 文件目录，每个文件代表一个概念（数据表、数据集、指标、操作手册、API 等），文件路径就是这个概念的唯一标识。

目录结构长这样：

sales/
├── index.md
├── datasets/
│   └── orders_db.md
├── tables/
│   ├── orders.md
│   └── customers.md
└── metrics/
    └── weekly_active_users.md

每个文件分两部分：顶部一小块 YAML frontmatter 存结构化字段，下面是 Markdown 正文，写什么完全自由。

一个完整的概念文件：

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column        | Type      | Description                              |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.        |
| `customer_id` | STRING    | FK to [customers](/tables/customers.md). |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

概念之间用普通 Markdown 链接互引，整个目录变成一张关系图，比文件系统的父子层级丰富得多。

合规条件就三条：每个非保留文件必须有可解析的 YAML frontmatter；frontmatter 必须包含非空的 type 字段；保留文件名（index.md、log.md）遵循规定结构。其他一切随意。

而且消费者被要求尽量宽容：不能因为缺少可选字段、遇到未知 type、多出额外 frontmatter key，甚至链接断了就拒绝解析。这设计哲学很有意思——宁可多读点废话，也别因为格式细节把合法内容挡在门外。

整个规范文件才 451 行、14.7 KB。Google 自己说的：Read the spec, it’s short! 这话倒没骗人。

Karpathy 的影子

OKF 不是凭空出来的。Karpathy 今年 4 月发了 LLM Wiki gist，两个月拿到 5000+ stars，核心思路就是"每个概念一个 Markdown 文件，LLM 负责维护，互链成图"。OKF 本质上是在标准化这个模式：把 Karpathy 的个人实践固化成一份开放规范，让不同团队、不同工具产出的知识库可以互相识别和消费。

我之前分析 RAG vs LLM Wiki 的取舍时说过，编译好的 wiki 有错误滚雪球、写入成本膨胀、分布式一致性这些问题。OKF 解决的是另一个层面的问题：如果大家都觉得 wiki 模式是对的，那格式得统一，不然你的 wiki 我的 wiki 各玩各的，还是没法流通。

Karpathy 估算过，维护得当的 Markdown 知识库相比直接灌原始文档，能减少高达 95% 的 token 消耗。OKF 想做的就是让这个"维护得当"有一个可遵循的底线。

AI 知识的四个层次

参考文章里提了一个我觉得很有意思的分层框架，把 AI 获取知识的方式拆成四层：

sitemap.xml 告诉爬虫哪些 URL 存在
llms.txt 告诉 agent 哪些页面最值得读
EntityMap 声明实体和它们之间的关系
OKF 把内容本身递到 agent 手里，每个页面是一个干净的概念，互链成图

这四层不是替代关系，是从索引到内容的递进。sitemap 回答"有什么"，llms.txt 回答"看什么"，EntityMap 回答"谁和谁有关"，OKF 回答"具体是什么"。OKF 补的是最后一公里，不是告诉你去哪找，而是直接把知识递给你。

三个设计原则

极简主义

OKF 对每个文件只要求一个字段：type。其他一切都留给内容创建者。存在哪些类型、包含哪些字段、正文写哪些部分，规范都不管。它定义的是互操作性接口，不是内容模型。

说实话，type 是唯一必填字段，意味着你可以把任何东西塞进去，只要标上 type。灵活，但也意味着两个 OKF bundle 可能长得完全不一样。“格式统一"只统一了最外层的壳，里面的内容组织还是各写各的。

生产者/消费者独立性

OKF 把知识编写者和使用者清晰分离。人手写的文件，AI agent 可以读。元数据流水线生成的 bundle，可视化工具可以浏览。一个 LLM 生成的 bundle，另一个 LLM 可以查询。格式是契约，两端工具可以独立替换。

格式本身，不是平台

OKF 不绑定任何云服务、数据库、模型厂商或 agent 框架。读写不需要专有账号或 SDK。

不过有意思的是，发布 OKF 的同一天，Google Cloud 也更新了 Knowledge Catalog，让它原生支持导入 OKF bundle。Knowledge Catalog 管的是 OKF 故意不碰的部分：存储、服务、查询、权限控制。开放格式，付费服务层。这策略眼不眼熟？

3 个参考实现

Google 随规范一起发布了 3 个参考实现：

enrichment agent：工作在 BigQuery 数据集上的数据增强 Agent。先针对每个表和视图写 OKF 概念文件草稿，再跑一遍 LLM 爬取权威文档，补充 schema、引用和关联路径。基于 Google ADK 构建，Gemini 做后端模型。
static HTML visualizer：把任何 OKF bundle 转成单个自包含 HTML 文件里的交互式图形视图。无需后端，数据不会离开页面。
3 个示例 bundle：GA4 电商数据集、Stack Overflow、比特币公开数据集。都是用上面的 enrichment agent 生成的，放在 repo 里作为格式合规的示例。

说点实在的

OKF 的极简设计方向是对的。Markdown 是人机共读的最佳折中，用文件路径做概念 ID 很聪明，YAML frontmatter 兼顾了结构化查询和人类可读。规范本身短到 451 行，降低了采纳门槛。

但社区也有不同声音。有人直接说"这不就是一个带 YAML frontmatter 的文件夹吗？“更尖锐的质疑是：如果目标消费者是 AI，为什么选 Markdown 而不是更结构化的 JSON 或 Protobuf？Markdown 嵌套表格渲染不好，复杂 schema 表达力有限。

我觉得关键在于 OKF 不替代 RAG 和 MCP，它们是互补的。RAG 处理大规模动态文档档案，OKF 处理稳定的、精选的组织知识。MCP 管的是 agent 怎么连工具和实时数据，是"插座”；OKF 管的是 agent 对数据源知道什么，是"流过插座的知识”。一个 MCP server 完全可以把 OKF bundle 作为知识源暴露出来。三者不在一个层面上竞争。

真正的顾虑是：OKF 还只是 v0.1。三天 3300 stars 说明社区有需求，但格式规范的真正考验不在发布而在采纳。需要多少生态工具跟上，多少团队真的用 OKF 格式出包，才能形成正循环？标准这东西，用的人多了才是标准，发布了没人用就只是一份文档。

写在最后

OKF 定义的是知识的流通格式，不是知识的替代品。格式能打通孤岛，但填进去的内容还得靠人。

为我的 Chaos Pool 开发一个“卖报童”机器人

hushan@kmoon.fun (Kmoon) — Tue, 16 Jun 2026 13:14:34 +0800

背景

我特别想喜欢飞书的 Link Preview 功能，就是在飞书群里发送一篇文章、一个 Github 仓库链接等等，会自动生成一个预览小卡片。

link preview 效果

这就很好地解决了我平时看到优秀的文章、知识、项目的时候，收藏了一堆链接，但是到后面看着一串 URL 无从下手，不知道每个链接是什么东西的问题。

为了管理从四面八方看到的有趣内容，我建了一个飞书群，命名为“Chaos Pool”，中文译为“混沌池”，本意是希望我每天从互联网搜刮来的信息，先扔进这个混沌池子，督促我有时间一定要吸收学习掉，然后将“混沌”转为“稳定”。

为此我专门用豆包为群聊生成了一个群头像，我最后选择了第一个：

豆包

需要一个“卖报童”

后面一段时间我都是这样的流程：平时逛 Github、微信公众号、V2EX、阮一峰网络周刊等等，遇到感兴趣、有意思、我能用上的东西，就长按复制链接、打开飞书、进入chaos pool群聊、粘贴链接、回车发送。这一套是不是看着还挺行云流水。

后来我慢慢发现，这样其实还是有点麻烦，中间很多环节都可以简化或者省略掉，我期望最终形态是：我复制链接、自动调起一个发送框、回车发送，至少在移动端这样才是我希望的流程。

而且还有一个问题，我经常看的社区、周刊、月刊，基本上都是定时发布，我每次还需要自己去对应的网站查看，我需要一个人（机器人）到点自动帮我推送到群里，有点像 RSS 订阅一样。

因此，我需要在飞书群里添加一个机器人，来完成上面这些任务，我给他起名为“卖报童”，这个名字也是通俗易懂。

添加飞书机器人

添加完飞书机器人后，我们得到了一个名为 webhook 的 https 链接，怎么用呢？

webhook 是什么？怎么用？

webhook 是什么？怎么用？我们点击查阅一下官方使用指南。看完发现没啥，可以理解为一个发送消息的接口，通过 webhook 请求可以在飞书群里发送消息。

那我们先简单调试一下，测试调用自定义机器人的 webhook 地址，向所在群组发送消息。：

curl -X POST -H "Content-Type: application/json" \
    -d '{"msg_type":"text","content":{"text":"啦啦啦！啦啦啦！我是卖报的小行家。"}}' \
    https://open.feishu.cn/open-apis/bot/v2/hook/****

我们可以看到群里收到了卖报童发来的卖报歌，：

这里遇到一个问题，通过机器人发送的链接没有生成预览卡片，我自己手动发送的明明可以生成卡片呀。

了解后发现“自定义机器人”不支持链接预览功能，需要创建一个“应用机器人”：

RAG vs LLM Wiki：“无状态”或成护城河?

hushan@kmoon.fun (Kmoon) — Sat, 13 Jun 2026 15:21:16 +0800

Reference：“无状态"是 RAG 的护栏

Karpathy 最近提了一个很有意思的方案叫 LLM Wiki —— 与其每次查询都重新检索一堆原始资料，不如让 LLM 先把所有文档读一遍，整理成一个结构化的知识库。以后有新文档进来，LLM 自动找出受影响的页面然后更新。查询的时候直接读 wiki，不用再翻原始材料了。

说实话我第一反应是：这不就是我理想中的知识管理吗？干净、有序、能自己生长。比 RAG 那种每次都从头翻文档的"笨办法"优雅太多了。

但仔细想想，这套方案的代价其实挺大的。而且有意思的是，这些代价恰恰是 RAG 那个"笨办法"天然避开的。

错误会滚雪球

RAG 拿给你的是原始文档的片段，你可以自己判断靠不靠谱。LLM Wiki 拿给你的是 LLM 写出来的东西——它理解错了、漏了关键信息、过度压缩导致失真，这些偏差会直接变成 wiki 里的"事实”。

更要命的是，错误会繁殖。LLM 处理第 15 篇论文的时候，参考了第 3 篇的摘要，而那个摘要本身就有偏差。基于偏差做了交叉引用，错误没被修正反而被放大了。后面所有查询都在这个有问题的基底上回答，lint 检查也是——lint 本身也是 LLM 跑的，它在有偏差的 wiki 上做检查，能查出什么？

这让我想到一个词：有状态的错误传播。一旦错误进入系统，它不是静止的，它会沿着依赖链扩散，而且你很难定位是哪个环节出了问题。

RAG 之所以没有这个问题，恰恰因为它每次都从源头重新来——上一次的错不会留给下一次。我们一直说 RAG"无状态"是局限，但换个角度看，这是道护栏。

写入成本膨胀

Karpathy 估算一篇新文档可能涉及 10-15 个 wiki 页面。听起来不多，但跑一下流程就知道了：LLM 先读完整篇新文档，再翻 index.md 找相关页面，然后读这十几页的内容判断怎么改，最后逐个重写。一篇文档的摄入就是几万到十几万 token。

更关键的是，这个成本不是恒定的。wiki 页面越来越多、越来越长，摄入第 101 篇时 LLM 要读的上下文比第 1 篇大得多。而 RAG 的摄入成本基本是恒定的——切分、embedding，完事，知识库再大也不会越来越贵。

两种模式的成本节奏也完全不同：RAG 是查询时花钱，按次付费；LLM Wiki 是写入时花钱，而且账单随规模往上走。对于查询量不大但资料持续涌入的场景，这个成本结构很致命。

分布式一致性的老问题

当 wiki 到了 200 个页面，一个新事实进来，LLM 怎么确保找全了所有该更新的地方？没法确保。更新了 mixture-of-experts.md 忘了改 training-cost-comparison.md，两个页面矛盾了，你大概率要碰巧都读到才能发现。

这本质上是分布式系统的一致性问题——只不过节点换成了 Markdown 文件。CAP 定理告诉我们这类问题没有银弹，交给 LLM 来扛，说实话我不太放心。

审计也是。RAG 能清楚告诉你答案来自哪几个 chunk，鼠标一点就能核对。LLM Wiki 呢？一个结论在第 5、12、18、23 次摄入时被改过，每次都是 LLM 当时理解的产物，原始信息在多次"传话"后溯源链早就断了。除非你给 wiki 上 git 版本控制并且每次 diff 审查——但真这么干，省下来的精力又贴回去了。

还有冷启动。开头最痛苦——你不知道该定什么结构，LLM 也不知道。如果方向错了，前几十篇的产物可能得推倒重来。后续理解深入了发现分类方式有问题要大规模重组，这跟代码重构一样疼，但这次是让 LLM 来重构，你对结果没有完全的把握。

适用场景较窄

LLM Wiki 最适合的其实是 Karpathy 自己的场景——个人研究笔记，几十到一两百篇材料，容错率高，错了也没什么大不了。结构化、知识密度高的内容（论文、技术报告）也还行。

但现实中大量场景不太适合：会议纪要和对话记录信息密度低、上下文咬合紧，拆成独立页面很勉强；代码仓库变化太快 wiki 追不上；法律合规文档一个字都不能动，摘要就有遗漏风险；实时数据根本没有"编译"的时间窗口。

写在最后

RAG 的"无状态"不是缺陷，是护城河。它保证了每一轮问答都能回溯到原始材料，不会把 LLM 的理解偏差一层层叠加上去。

但这不代表只能二选一。更务实的路线是把 LLM Wiki 定位成缓存层和知识导航——用它建立高层知识地图，帮你快速定位该看的范围，真正作答时还是回到原始文档做最终核验。

编译是为了提速和导航，不是为了取代信源。

代码定义结构，权重存储知识

hushan@kmoon.fun (Kmoon) — Fri, 12 Jun 2026 09:47:25 +0800

Reference: 代码定义结构，权重存储知识：一个例子看懂大模型如何推理

Ollama 本地部署模型

Ollama

先下载好 Ollama

然后选择一个模型本地部署，这里选择 llama3

一行命令部署好，测试一下

Ollama 本地保存模型的目录结构，其中 blobs 是真正占空间的权重文件，manifests 是模型配置/索引（很小），这里就有一个奇怪的现象：模型的代码只有几十到几百 KB，权重文件却有几个 GB，甚至几十GB。

.ollama/
└── models/
├── blobs/       # 实际权重文件（GGUF 格式，GB 级）
└── manifests/   # 模型元数据（JSON，KB 级）

因为 Ollama blobs 里存的 GGUF 是量化后的权重二进制文件，全部浮点数参数都存在这里；manifests 只是模型描述、层数、上下文窗口、量化精度等配置，不含知识。

我们可以看到 llama3:latest 模型权重有 4.7 G。为什么差距这么大，我们跟模型交互对话时，模型代码和模型权重是如何配合的？模型代码大小和权重大小到底谁对模型更重要？

最小模型

我们从一个只有 3 个参数的小模型开始，一步步走完整个推理过程。

假设我要做一个判断天气的小模型。根据温度和湿度判断是否适合出门，输入：温度 temp、湿度 humidity，输出：适合出门的分数 y。其中w1、w2 分别是温度和湿度对应的权重，b 是偏置。

class WeatherModel:
    def __init__(self):
        self.w1 = None
        self.w2 = None
        self.b  = None

    def forward(self, temp, humidity):
        return temp * self.w1 + humidity * self.w2 + self.b

模型训练的过程就是逐渐确定w1、w2、b这三个参数的过程。我们收集了很多历史天气数据中的温度、湿度的值，并打上是否适合出门的标记，这个就是模型训练过程中的训练数据。训练的过程，就是不断调整 w1、w2、b，让模型输出越来越接近真实结果。

经过大量的迭代，最后得到：

w1 = 0.7
w2 = -0.3
b  = 5.0

这三个数字就是模型权重，训练结束后模型保留的只有这三个数字，这些数字其实是历史经验的压缩结果。即权重 = 从训练数据中提炼出来的经验。对于我们使用的大模型，道理完全一样，只不过区别在于大模型的参数数量扩大了几十亿倍。千亿参数大模型只是把无数层类似 w * x + b 的矩阵运算堆叠、加上注意力机制，底层计算逻辑本质仍是权重与输入的线性运算，只是结构更复杂。

后面我们得到了一组新的温度值、湿度值，送入模型进行计算，得出适合出门的分数，如果分数低于我们设定的阈值，就判断为不适合出门。整个过程中：代码决定怎么算、权重决定用什么数字算，二者缺一不可。

结构 vs 权重

模型结构 = 大脑，模型权重 = 记忆。或者说模型结构 = 神经系统，模型权重 = 学到的知识。

一个模型结构可以搭配多个权重，比如英文模型和中文模型就可以搭配不同的预训练权重。

同一套 Llama3 Transformer 代码结构，加载英文通用权重 = 英文对话模型；加载代码微调权重 = 代码助手；加载医疗微调权重 = 医疗问答模型。

因此真正决定模型能力的，往往不是结构文件，而是权重文件，因为权重文件代表模型学到了多少知识。

模型推理过程

模型加载完成后，会把权重全部放进显存，然后开始推理。CPU 负责指挥，GPU 负责干活，CPU 负责告诉 GPU 执行第 1 层、执行第 2 层、…，GPU 负责真正计算矩阵乘法。推理时，权重常驻显存。输入数据不断流过这些权重矩阵。

CPU：处理文本分词、token 预处理、调度计算流程、控制网络层执行顺序；
GPU：承载全部权重矩阵，并行执行海量矩阵乘，是推理算力核心；

写在最后

真正庞大的从不是复杂的算法代码，而是训练过程中沉淀下来的亿万数值。

我们说大模型 “大”，不在于实现代码有多冗长，而在于它承载了海量学习得来的知识。

代码搭建出神经网络的完整结构，相当于塑造大脑的生理框架；

权重存储全部训练学到的信息，相当于大脑里积累的记忆；

所谓推理，本质就是将输入文本转化为向量，不断穿过每一层承载知识的权重矩阵，最终输出对应的结果。

Agent = Model + Harness

hushan@kmoon.fun (Kmoon) — Tue, 09 Jun 2026 19:36:02 +0800

程序 = 数据结构 + 算法

zhlgd-cli：尝试做一个 CLI

hushan@kmoon.fun (Kmoon) — Sun, 07 Jun 2026 17:01:02 +0800

一直觉得在命令行里敲命令然后回车，有一种莫名的爽感，特别是当黑框里返回自己想要的东西的时候。

AI 这两年发展很快，CLI（Command Line Interface）也被重新推到了舞台中央。平时我们常用的 GUI，对人类当然很友好，但对 Agent 来说未必是最高效的工作方式。能直接发命令、拿结果、继续串联下一步，这种交互反而更适合 AI 干活。

目前互联网上最火的 CLI 之一，应该就是字节跳动开源的飞书 CLI（lark-cli）。它能让人类和 Agent 都在终端里操作飞书，比如收发消息、创建文档、多维表格、查询日历和会议等等。

CLI 对 Agent 来说，本质上也是一种工具调用，而且很多时候还是更顺手的一种工具。所以，为了紧跟 AI 发展，我决定尝试自己写一个 CLI，看看这东西到底是怎么落地的。

先想需求

不管干什么，总得结合实际需求，毕竟没实际用途，做着也没劲。仔细想了想，我日常能接触到的场景也就来自两方面：学校、公司。公司这边肯定没法下手，压根不需要我；字节这边每天都会有层出不穷的工具，各种花色任你选择，说实话真有点“军备竞赛”那味道了。

所以我把思路转移到学校这边。学校这边能做的感觉挺多，毕竟学校的网站、各种平台都比较老旧，有些交互也确实不够顺手。突然想到智慧理工大，武理一个大家日常都会用到的大 OA 平台，而且最近还刚改版，那就干脆拿它来练手，试试把它 CLI 化。

开发流程

第一步肯定是先了解一下 CLI 的开发流程。我现在除了知道应该要用 Node.js 开发，其他几乎是零基础。那就老老实实先上网搜。

搜索 Node.js CLI

找到了一篇 2019 年的知乎文章：用Node.js开发一个Command Line Interface (CLI)。本来我看到这个时间，第一反应是打算划走，但换个思路一想，这么久远的文章还能被我搜到，说不定反而是一篇优质内容，而且标题也非常直白，所以我还是决定仔细看一看。

看完之后，大概就知道整个流程是什么样了。和我预想得差不多，确实是用 Node.js 开发，难怪平时网上安装 CLI 的时候都会让我先确保本地有 Node 环境，而且很多工具都是直接用 npx 起。

开发流程大概可以分成下面几步：

创建 npm 模块
增加 bin 入口文件
全局安装
发布

这么一看，整个路径其实还挺清晰的。先把最小可用版本做出来，再往上加子命令就行。

环境配置

先简单配置一下 Node.js 环境。我平时一般用 nvm 管理 Node 版本，毕竟我之前真的因为版本差异排查过很久 bug，这种坑踩过一次就够了。

Node 环境配好之后先检查一下：

本地 Node 环境检查结果

创建 npm 模块，直接执行：npm init

使用 npm init 初始化项目

这样就初始化好了整个项目：

{
  "name": "zhlgd-cli",
  "version": "1.0.0",
  "description": "武汉理工大学智慧理工大命令行工具",
  "homepage": "https://github.com/kmoonn/zhlgd-cli#readme",
  "bugs": {
    "url": "https://github.com/kmoonn/zhlgd-cli/issues"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/kmoonn/zhlgd-cli.git"
  },
  "license": "MIT",
  "author": "Kmoon",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

type 这里选择 module，因为新版 ES 模块化用的是 import/export，现在做 CLI 基本都会用到。

commonjs 则是老版 Node.js 模块化，写法是 require()。

接着在 package.json 里增加 bin 字段：

{
  "bin": {
    "zhlgd": "./bin/index.js"
  }
}

这里也顺便记一下：

zhlgd-cli 是项目名 / 包名
zhlgd 才是最终在终端里执行的命令

在项目根目录新建一个 bin 文件夹，并在里面新建一个 index.js 文件。

文件结构长这样：

zhlgd-cli/
├── bin/
│   └── index.js
└── package.json

编写 bin/index.js 代码。

第一行必须写：#!/usr/bin/env node，意思是告诉系统用 Node 来运行这个脚本。

#!/usr/bin/env node

// 你的命令行逻辑开始
console.log('✅ 智慧理工大命令行工具启动成功！');
console.log('👉 命令：zhlgd');

然后全局安装，把命令链接到本地环境。

在项目根目录执行：

npm link

和下面图片一样，基本就说明成功了。

npm link 成功后的终端输出

这个阶段主要是本地开发调试方便。我后面把它正式发到了 npm 上，所以现在除了 npm link 这种本地联调方式之外，也可以直接下载安装：

npm i zhlgd-cli

能走到这一步，我自己其实还挺开心的。因为它说明这个项目已经不只是我本地电脑上的一个小玩具，而是真的变成了一个别人也能装下来体验的 CLI。

然后测试一下我们的命令。新开一个终端输入 zhlgd，就可以直接看到输出：

首次运行 zhlgd 命令的输出

到这一步，其实最小可用 CLI 就已经搭起来了。后面要做的，就是继续往里面塞真正有用的子命令。

zhlgd help

接下来先完成第一个最简单的命令，也是几乎每个 CLI 都会有的命令：help。

这里认识一个新东西，官方很常见的 CLI 开发框架：commander。

先安装一下依赖：

npm install commander

写着写着我发现，help 其实根本不用自己手搓，框架已经给你做好了。

下面是使用 commander 改造后的入口文件 index.js：

#!/usr/bin/env node

// 导入 commander 库，用于处理命令行
import { Command } from 'commander';
const program = new Command();

// 配置 CLI 基础信息
program
  .name('zhlgd')
  .version('1.0.0', '-v, --version')
  .description('一个基于 Node.js 开发的智慧理工大 CLI 工具');

// 解析命令行输入的参数
program.parse(process.argv);

这一步虽然简单，但我感觉挺关键。因为从这里开始，这个项目才不只是一个“能打印一句话的脚本”，而是开始往真正的 CLI 工具靠了。

运行一下看看效果：

zhlgd help 命令输出

下面开始啃一个硬骨头：登录。毕竟只有先登录，后面的事情才做得下去。

智慧理工大的登录是单点登录，大概流程如下：

用户输入账号、密码 → 点击登录
前端校验：账号/密码不能为空
记住密码：写入 Cookie（加密存储）
向后端请求 RSA 公钥
使用公钥 加密账号、密码
把加密后的账号密码塞进表单隐藏域
自动提交登录表单 → 后端验证 → 登录成功 / 失败

每次登录时，前端都会先请求后端获取 RSA 加密公钥：

// 获取 key
$.ajax({
  url: 'rsa?skipWechat=true',
  dataType: 'json',
  type: 'POST',
  success: function (data) {
    var encrypt = new JSEncrypt();
    encrypt.setPublicKey(data.publicKey);
    $('#ul').val(encrypt.encrypt(u));
    $('#pl').val(encrypt.encrypt(p));
    $('#loginForm')[0].submit();
  },
});

网页里这一步看起来很自然，因为浏览器已经帮你把表单提交、跳转、Cookie 处理这些事情都包掉了。但放到 CLI 里，这些步骤就得自己一层层补出来。

也就是说，在 CLI 里，登录这件事至少要做下面几步：

请求 RSA 公钥
用公钥加密账号和密码
提交登录请求，拿到 ST ticket
根据 ticket 继续跟重定向，换取完整 Cookie
把 Cookie 保存到本地，后续命令统一复用

对用户名和密码加密之后，再提交登录请求获取 ST ticket，接着顺着重定向把完整 Cookie 换回来，并保存到本地，后续都拿这份 Cookie 作为鉴权使用：

// 5. 用 ST 换取完整 Cookie
const st = extractTicket(loginResp.headers.location);
await followRedirects(`${SERVICE}?ticket=${st}`, cookieJar, commonHeaders);

// 6. 保存
saveCookies(cookieJar);

这里我自己的体感是，登录这一关是整个 CLI 最麻烦的部分。因为一旦 Cookie 这套机制没打通，后面所有需要鉴权的接口都跑不起来；但只要这一关打通了，后续子命令反而会顺很多，本质上就变成“带上鉴权去请求接口，再把结果整理一下输出”。

下面演示一下登录过程。这里为了安全，密码输入做了隐藏处理：

zhlgd login 命令的隐藏密码输入效果

到这里，login 命令就算是跑通了。现在这个项目也已经正式发到了 npm 上，直接执行下面这条命令就可以安装：

npm i zhlgd-cli

npm

所以如果你只是想直接上手体验，而不是自己从头本地联调，走 npm 安装会更方便。具体实现细节如果感兴趣，也可以直接看源码：zhlgd-cli GitHub 仓库。

zhlgd msg & news

登录搞定之后，我先做了两个最基础、也最容易验证成果的功能：

zhlgd msg：查看我的消息
zhlgd news：查看校园新闻

之所以先做这两个，是因为它们很适合拿来验证整条链路是不是已经通了：

登录是否真的拿到了可用 Cookie
Cookie 是否已经被正确保存
后续子命令是否能稳定复用这套鉴权能力

实现上其实没有想象中那么玄学，核心就是把两个接口分别转成 JavaScript 请求：

const data = await apiRequest(
  `${BASE_URL}/tp_up_new/up/newhome/getFpMsgList`,
  { MSG_TYPE: '3' },
);

const data = await apiRequest(
  `${BASE_URL}/tp_up_new/up/newhome/getNewsNotice`,
  { channel: '13962' },
);

真正关键的地方，还是请求时要把登录成功后保存下来的 Cookie 带上：

/**
 * 带鉴权的 API 请求，未登录时自动提示
 */
export async function apiRequest(url, body) {
  if (!isLoggedIn()) {
    console.log('⚠️  未登录，请先执行 zhlgd login');
    process.exit(1);
  }
  const cookies = loadCookies();
  const resp = await axios.post(url, body, {
    headers: {
      ...API_HEADERS,
      cookie: cookieHeader(cookies),
      'User-Agent': UA,
    },
  });
  return resp.data;
}

所以说，前面把 login 打通之后，后面很多功能的开发思路就都统一了：

找到对应接口
搞清楚请求参数
带上登录态发请求
把返回结果整理成终端里更适合看的样子

下面测试一下实际效果：

zhlgd msg 命令输出效果

zhlgd news 命令输出效果

看到这里，我自己其实还挺有成就感的。因为它已经不再只是一个能打印几行字的 demo，而是真的具备了“登录 -> 带鉴权请求 -> 输出结果”这一整套能力。

写在最后

这次折腾 zhlgd-cli，对我来说最有意思的地方，不是把 help 命令跑起来，而是第一次比较完整地把“网页里浏览器偷偷帮你做的事情”，一点点搬到了 CLI 里。

目前这个 CLI 至少已经把最难的登录流程打通了，也做出了 msg 和 news 这两个能实际用起来的子命令。后面如果继续往下做，其实就可以顺着这条路继续扩，比如把更多查询类功能搬进终端，甚至再往前走一步，给 Agent 直接调用。

总之，这次尝试让我更直观地感受到一件事：CLI 这种东西，看起来很“黑框”，但一旦场景选对了，真的会很顺手。尤其是在 AI 时代，它不只是给人用的工具，很多时候也天然适合给 Agent 干活。