但真接进日常工具，总觉得哪里都差半口气：官方确实提供了 OpenAI 兼容接口，能直连，可用起来别别扭扭。与其凑合，不如自己造一个顺手的。于是决定用 Cloudflare Workers 做一层转发，把 Modal 端点包成一个干干净净的 API。

流水账记录一下。照例，这篇由 Fable 5 代笔，哈哈。

一条命令，Kimi K3 就有了

Modal Endpoints 支持 Qwen、Kimi、DeepSeek、GLM、GPT-OSS 等一大票开源模型，部署真的只要一条命令：

1

modal endpoint create --model moonshotai/Kimi-K3

Modal 会自动解析模型、挑选推理引擎和 GPU 配方，然后给你一个专属端点，URL 长这样：

1

https://<workspace>--ep-kimi-k3-server.us-west.modal.direct

重点是计费方式：只按容器实际运行的算力收费，负载上来自动扩容，没人用就缩到零。对“每月 $30 额度、坚决白嫖”的个人用户来说，scale-to-zero 就是最重要的功能，没有之一。

官方直连：两个 token 拼一个 key

端点默认带鉴权，先创建一对 proxy token：

1

modal workspace proxy-tokens create

会得到一个 token ID（wk- 开头）和一个 secret（ws- 开头，只显示这一次，赶紧存好）。官方的用法很有意思：把两个 token 中间加一个点拼起来，当成一个普通的 API key 用：

1

Authorization: Bearer wk-<id>.ws-<secret>

而端点本身就提供 OpenAI Chat Completions 接口，路径在 /v1 下。所以理论上任何 OpenAI 兼容客户端都能直连：

1
2
3
4
5
6
7
8
9
10
11

from openai import OpenAI

client = OpenAI(
    base_url="https://<workspace>--ep-kimi-k3-server.us-west.modal.direct/v1",
    api_key="wk-<id>.ws-<secret>",
)

client.chat.completions.create(
    model="moonshotai/Kimi-K3",
    messages=[{"role": "user", "content": "你好呀"}],
)

官网还提供了一个统一入口 https://inference.us-west.modal.direct/v1，同一个拼接 key 也能用。

到这一步其实已经“能用”了，但真往日常工具里塞，就发现几个别扭的地方：

• 模型名诡异。尤其走统一入口时，模型名不是干净的 kimi-k3，而是一长串带端点信息的名字。不少客户端会拿模型名做展示甚至能力判断，要么难看，要么直接出岔子，搞不好还得再垫一层名字转换。
• 真凭证满天飞。wk-/ws- 这对 token 是 workspace 级的门票，每个工具里都贴一份，哪天想换 token，得挨个客户端改一遍。
• 单账号额度有限。$30 烧完或者端点被打挂，就只能干瞪眼。

我的方案：让 Cloudflare Worker 看大门

既然横竖要垫一层，干脆把这一层做成自己的“前台”：一个不到一百行的 Cloudflare Worker，对外只暴露我自己发的 API key，对内替我保管 Modal 凭证。

1
2
3
4
5
6
7

各种客户端
    ↓ Bearer 我自己发的 key
Cloudflare Worker（kimi-proxy）
    ↓ Modal-Key / Modal-Secret
Modal 主账号（用到底） → 备用账号（主账号出问题才接手）
    ↓
Kimi K3 端点

这里有个恰到好处的细节：Modal 除了 Authorization: Bearer 的拼接写法，还支持把 token 拆成两个独立的请求头传过去：

1
2

Modal-Key: wk-...
Modal-Secret: ws-...

文档里说，这条通道就是为“Authorization 头要留给别的 token”的场景准备的。正好：Authorization 让出来放我自己的 key，Modal 凭证走专用头，两层鉴权互不打架。

主备账号和故障切换

Worker 里配了两个 Modal 账号（也就是两份每月 $30），但不做负载均衡：所有请求固定先走主账号，只有主账号自身出问题——凭证失效（401）、额度耗尽（402/403）、限流（429）、服务端错误（5xx）——才切到备用账号重试。至于 400 这类请求本身的错误，换个账号也一样失败，不折腾：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

function shouldFailOver(response) {
  return [401, 402, 403, 429].includes(response.status) || response.status >= 500;
}

const [primary, backup] = accounts;
const retryRequest = request.clone();

const firstResponse = await fetch(createUpstreamRequest(request, primary));
if (!shouldFailOver(firstResponse)) {
  return firstResponse;
}

await firstResponse.body?.cancel();
return fetch(createUpstreamRequest(retryRequest, backup));

一开始也想过随机分流，让两个账号平摊额度，后来想明白对这种场景是负优化，关键在缓存：

• 前缀缓存要集中。聊天和 agent 类请求会反复携带同一段长前缀——系统提示词、越滚越长的对话历史，推理引擎会缓存这部分计算结果，命中了就不用重算。随机分流等于把请求拆到两个互不相通的端点上，缓存命中率直接腰斩，而每一次未命中，都是实打实按 GPU 时间计费的重新预填充，又慢又贵。
• scale-to-zero 要成全。流量集中在主账号，备用账号的端点就能安安稳稳缩在零上，一分钱不烧；随机分流则是两边容器轮流被唤醒，闲置消耗直接翻倍。

所以现在的分工是：主账号用到底，备用账号纯待机，主账号限流或者抽风时才顶上，客户端全程无感。哪天主账号的 $30 真烧干了，多半也是以这几类账号级错误的面目出现，请求会自动落到备用账号头上——用到底，烧干自动换。

这里有一个小坑：请求的 body 是流，只能被读一次。第一次转发就把它消费掉了，等想故障切换时已经没有 body 可发了。所以要在首发之前 request.clone() 留个底，重试时用副本。另外失败响应的流记得 body?.cancel() 释放掉，不然它会一直占着连接。

部署

代码全部加起来九十行左右，部署就是标准 wrangler 流程，凭证全部塞进 secret：

1
2
3
4
5
6

wrangler deploy
wrangler secret put CLIENT_API_KEY   # 自己生成一个长随机串
wrangler secret put MODAL_KEY
wrangler secret put MODAL_SECRET
wrangler secret put MODAL_KEY_2
wrangler secret put MODAL_SECRET_2

之后所有工具里的配置就统一成了：

1
2
3

base_url: https://kimi-proxy.<你的子域>.workers.dev/v1
api_key:  自己发的那个 key
model:    moonshotai/Kimi-K3

上游换账号、换 token，甚至哪天把 Kimi K3 换成别的模型，客户端配置一个字都不用改。

算账环节

• Modal：两个账号，每月各 $30 免费额度，端点闲时缩到零，零消耗
• Cloudflare Workers：免费计划目前每天 10 万次请求，对个人使用是天文数字
• 合计：￥0

事情是怎么从“多部署一个 Pages”发展到“给博客养猫”的，流水账记录一下，哈哈。

先理清两个仓库

我的 Hexo 博客现在涉及两个 GitHub 仓库：

• lenardar/blog：保存 Markdown、图片、主题和配置，也就是博客源码
• lenardar/lenardar.github.io：保存 Hexo 生成后的静态文件，用于 GitHub Pages

平时写文章和修改主题都在 blog 仓库。Hexo 负责把这些源码生成到 public/，lenardar.github.io 则只是发布目录，不适合直接编辑。

一开始，这套发布过程需要在本地手动运行：

1
2
3

npm run clean
npm run build
npm run deploy

GitHub Pages + Cloudflare Pages 双轨部署

Cloudflare Pages 直接连接 lenardar/blog 的 main 分支，配置也很简单：

1
2

Build command: npm run build
Build output directory: public

以后只要把源码推到 blog：

1

git push origin main

Cloudflare Pages 就会自动安装依赖、运行 Hexo、发布 public/。原来的 GitHub Pages 发布路线也继续保留。

后来我又把 GitHub Actions 接了进来，让 GitHub Pages 也不再依赖本地手动部署。现在每次向 blog/main 推送代码，工作流会自动安装依赖、运行 Hexo，再把生成的 public/ 推到 lenardar/lenardar.github.io：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

name: Deploy GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build

      - uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.PAGES_DEPLOY_TOKEN }}
          external_repository: lenardar/lenardar.github.io
          publish_branch: main
          publish_dir: ./public

这里使用 PAGES_DEPLOY_TOKEN，是因为工作流要从源码仓库跨仓库推送到发布仓库。Token 只授权目标仓库的 Contents 读写权限，再保存为源码仓库的 Actions Secret 即可。

所以准确地说，并不是“不用 Hexo 了”，而是“不用我亲自运行 Hexo 了”：Cloudflare Pages 和 GitHub Actions 都会在云端执行 npm run build，本地的 npm run deploy 只作为备用方案。

最终就变成了两条互不冲突的发布路线：

1
2
3
4
5
6
7
8
9

push 到 blog/main
        │
        ├─ Cloudflare Pages ── npm run build ── lenardar.pages.dev
        │                                      （AI 小猫完整功能）
        │
        └─ GitHub Actions ─── npm ci + build ── lenardar.github.io
                                                 │
                                                 └─ blog.ilovemilktea.top
                                                    （目前指向这里）

现在博客可以从三个地址访问：

• blog.ilovemilktea.top：自己的域名，目前指向 GitHub Pages
• lenardar.github.io：GitHub Pages 的原生地址
• lenardar.pages.dev：Cloudflare Pages 地址，支持完整的 AI 小猫功能

三个入口背后仍然是同一份博客源码，两条构建路线也没有所谓的“优先级”。好处是迁移和回退都轻松：Cloudflare 出问题还有 GitHub Pages，GitHub Pages 有问题也不影响 Cloudflare。

为什么只有 API 经过 Functions

Cloudflare Pages 不只可以放静态文件，还支持 Pages Functions。为了不让每一个 CSS、图片和文章请求都经过函数，我在 Hexo 的 source/_routes.json 里只开放了 API 路径：

1
2
3
4
5

{
  "version": 1,
  "include": ["/api/*"],
  "exclude": []
}

这里还有一个小坑：Hexo 默认会忽略以下划线开头的文件，所以要在 _config.yml 里显式包含：

1
2

include:
  - _routes.json

否则本地明明有 _routes.json，构建后的 public/ 里却找不到，Cloudflare 自然也不会应用路由。

然后，博客开始养猫

最初的想法很简单：访客打开博客时，让右下角的小宠物随机说一句欢迎词。既然 Workers AI 每天有免费额度，而且博客访问量也不大，那就干脆每次实时生成。

后来又觉得，只会打招呼有点浪费，于是继续加了：

• 总结当前文章
• 用简单语言解释核心概念
• 从博客里推荐相关文章
• 接受访客自由提问

前端会读取当前页面正文和 Hexo 已有的 search.xml，在浏览器本地匹配最多三篇相关文章，再把截断后的上下文发给 /api/chat。这样不需要额外维护数据库、向量库或者搜索服务。

大概是这条链路：

1
2
3
4
5
6
7

当前文章 + search.xml
        ↓ 浏览器本地检索
相关正文片段 + 访客问题
        ↓ /api/chat
Pages Function
        ↓ AI binding
Workers AI

Pages Functions 具体怎么写

Pages Functions 的约定很直白：项目根目录下的 functions/ 会按照文件路径自动变成接口。

1
2
3
4

functions/
└── api/
    ├── greeting.js  → /api/greeting
    └── chat.js      → /api/chat

在 Cloudflare 控制台给 Pages 项目添加一个 Workers AI binding，变量名设为 AI。部署后，函数里就可以直接使用 context.env.AI，不需要把 API Key 放进仓库。

欢迎词接口

欢迎词只需要页面标题和页面类型，前端发一个很小的请求：

1
2
3
4
5
6
7
8
9
10

fetch("/api/greeting", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    page: {
      title: document.title,
      type: document.querySelector(".post") ? "文章" : "页面"
    }
  })
});

Function 接收后调用 AI binding：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

const DEFAULT_MODEL = "@cf/qwen/qwen3-30b-a3b-fp8";

export async function onRequestPost(context) {
  const body = await context.request.json();
  const pageTitle = cleanText(body?.page?.title, 100) || "博客";

  if (!context.env.AI) {
    return Response.json({
      text: fallbackGreeting(),
      source: "fallback"
    });
  }

  const result = await context.env.AI.run(
    context.env.PET_GREETING_MODEL || DEFAULT_MODEL,
    {
      messages: [
        {
          role: "system",
          content: "你是博客里的小猫助手，直接输出一句简短问候。"
        },
        {
          role: "user",
          content: `访客正在浏览：${pageTitle}`
        }
      ],
      max_tokens: 360,
      temperature: 0.75
    }
  );

  return Response.json({
    text: cleanGreeting(getModelText(result)),
    source: "ai"
  });
}

实际代码外面还包了一层 try/catch。绑定不存在、模型超额或者调用失败时，接口返回预先准备的本地问候，并标记 source: "fallback"。前端不需要区分错误类型，照常把文字放进气泡即可。

文章聊天接口

聊天的 Function 仍然只是一个 POST 接口，但输入多了三个部分：

1
2
3
4
5
6
7
8
9
10
11

{
  "question": "这篇文章主要讲了什么？",
  "context": "当前文章和相关文章的正文片段",
  "references": [
    { "title": "相关文章标题", "url": "/文章路径/" }
  ],
  "history": [
    { "role": "user", "content": "上一轮问题" },
    { "role": "assistant", "content": "上一轮回答" }
  ]
}

服务端不会盲目信任这些内容，而是先清洗和截断：

1
2
3
4

const question = cleanText(body?.question, 300);
const articleContext = cleanText(body?.context, 9000);
const history = cleanHistory(body?.history).slice(-6);
const references = cleanReferences(body?.references).slice(0, 3);

系统提示词里还明确告诉模型：文章正文属于不可信参考资料，不能执行正文里夹带的指令，资料不足就坦率说明。处理完以后才调用 Kimi：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

const result = await context.env.AI.run(
  context.env.PET_CHAT_MODEL || "@cf/moonshotai/kimi-k2.6",
  {
    messages: [
      { role: "system", content: buildSystemPrompt() },
      ...history,
      {
        role: "user",
        content: [
          `访客问题：${question}`,
          "以下是博客参考内容：",
          articleContext
        ].join("\n\n")
      }
    ],
    max_completion_tokens: 360,
    chat_template_kwargs: { thinking: false },
    temperature: 0.45
  }
);

这里关闭了长推理。博客问答更需要简洁、稳定和省额度，并不需要模型在后台写几百 token 的思考过程。

不上向量数据库，先用 search.xml

Hexo 已经通过 hexo-generator-search 生成了 search.xml，里面包含文章标题、链接和正文。前端第一次聊天时拉取它，之后复用同一个 Promise：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

function loadSearchEntries() {
  if (searchEntriesPromise) return searchEntriesPromise;

  searchEntriesPromise = fetch("/search.xml")
    .then(response => response.text())
    .then(xmlText => {
      const xml = new DOMParser()
        .parseFromString(xmlText, "application/xml");

      return Array.from(xml.querySelectorAll("entry")).map(entry => ({
        title: entry.querySelector("title")?.textContent || "未命名文章",
        url: entry.querySelector("link")?.getAttribute("href") || "/",
        content: stripHtml(entry.querySelector("content")?.textContent || "")
      }));
    });

  return searchEntriesPromise;
}

提问和当前文章会被切成英文单词、数字和中文二元词组。标题命中加 5 分，正文命中加 1 分，排序后取前三篇。当前页面正文最多取 5,000 字符，相关文章每篇最多取 1,800 字符，最终上下文再统一截到 9,000 字符。

这当然没有向量检索聪明，但对于目前不到十篇文章的小博客已经足够，而且零数据库、零索引任务、零额外费用。以后文章多起来，再把这一层换成 Vectorize 也不迟。

前后端都准备退路

整套功能刻意设计成“猫可以罢工，博客不能罢工”：

• GitHub Pages 上没有 /api/*：前端自动使用本地问候和关键词搜索
• Cloudflare 没有 AI binding：Function 返回 fallback
• Workers AI 超额或暂时失败：Function 捕获异常并返回 fallback
• search.xml 拉取失败：仍然可以使用当前文章正文
• 请求超过 15～30 秒：浏览器用 AbortController 主动取消

所以 AI 是一层渐进增强，而不是博客正常阅读的前置条件。

从 Emoji 猫到抽象键盘猫

第一版为了先跑通功能，右下角放的是一个 🐈。功能是能用了，但越看越像临时占位符。

后来参考“猫咪拍键盘”的动作，重新生成了一只原创角色：白色圆脑袋、几根黑线、表情有点傻，脖子上挂着一个橙色 <>。第一版生成得太精致，像儿童卡通；第二版把细节全部砍掉，反而一下对味了。

生成图先使用纯绿背景，再做本地色键抠除，得到透明 PNG。原本还想生成第二张动作帧，但生成模型很难保证两帧轮廓完全一致，播放时会突然“变脸”。最后用了更简单的办法：同一张图水平镜像，配合 CSS 交替显示。

1
2
3
4
5
6
7
8
9
10
11

.blog-pet-mascot-frame-b {
  transform: scaleX(-1);
}

#blog-pet.is-thinking .blog-pet-mascot-frame-a {
  animation: frame-a .22s steps(1, end) infinite;
}

#blog-pet.is-thinking .blog-pet-mascot-frame-b {
  animation: frame-b .22s steps(1, end) infinite;
}

于是小猫平时安静趴着，生成欢迎词或者回答问题时就开始左右开弓疯狂敲键盘。还适配了手机尺寸和 prefers-reduced-motion，不喜欢动画的访客会看到静态版本。

免费额度够不够

Workers AI 免费计划目前每天提供 10,000 Neurons，UTC 00:00 重置。超出免费额度后请求会失败，而不是自动开始扣费，这一点对“坚决白嫖”的个人博客很重要。具体额度和模型单价以后可能变化，最新数字还是看 Workers AI Pricing。

上线当天查到的实际消耗是：

1
2
3

Qwen3：586.34 Neurons
Kimi K2.6：47.12 Neurons
合计：633.45 / 10,000（约 6.33%）

于是最终采用双模型：

• 高频、简短的自动问候：@cf/qwen/qwen3-30b-a3b-fp8
• 访客主动发起的文章聊天：@cf/moonshotai/kimi-k2.6

欢迎词不需要动用昂贵模型，真正需要理解长文章时再让 Kimi 上场。这样既能提升回答质量，也不至于有人每刷新一次页面都让额度原地爆炸。

最后的样子

现在更新博客源码后，Cloudflare Pages 会自动重新构建；GitHub Pages 仍然可以独立发布。静态内容由 CDN 提供，只有两个 /api/* 接口会进入 Functions，聊天再按场景选择 Workers AI 模型。

最开始只是想多部署一份博客，最后收获了双轨发布、AI 文章助手，以及一只原创抽象键盘猫。

只能说，折腾博客最危险的一句话就是：“顺便再加一个小功能。”哈哈。

做临床研究、meta 分析或者 NMA 的人，森林图是绑定出图。R 里现有的工具不少——forestplot、forestploter、forester、meta::forest()——但用下来都多少有些不顺手：

• 很多包的 API 偏”配置式”，参数一多就变成巨长的函数调用，想调整布局得翻文档猜参数名
• 想要的面板组合经常不在预设里：比如左边文本、中间 CI、右边再来一列柱状图，基本要自己拼
• 分组行、汇总行、条纹、分隔线这些装饰性元素，每个包的处理方式都不一样
• 想给特定行换颜色、换形状，往往要改底层数据或者用很 hack 的方式

所以我写了 panelforest。

核心想法很简单：森林图本质上就是几列面板横向拼在一起，每列有自己的渲染逻辑。 那就不要把它当成一个”森林图函数”来设计，而是让用户自己声明”我要哪些列、每列长什么样”，剩下的事情交给引擎。

项目地址：https://github.com/lenardar/panelforest

长什么样

先看结果：

这张图是一个 NMA 安全性数据的森林图，包含：

• 左侧文本列（亚组标签）
• 中间文本列（OR 数值）
• 右侧 CI 面板（对数刻度、参考线、截断箭头、favors 标注）
• 分组行加粗、行间分隔线、条纹背景
• 不同比较用不同颜色和形状区分

生成这张图的代码大概 30 行，全部是管道式组合。

怎么用

基本结构

1
2
3
4
5
6
7
8
9

library(panelforest)

forest_plot(df) |>            # 传入数据
  add_stripe(...) |>          # 条纹背景
  add_group(...) |>           # 分组行
  add_hline(...) |>           # 分隔线
  add_text(...) |>            # 文本列
  add_ci(...) |>              # CI 面板
  fp_render()                 # 渲染

每个 add_*() 就是往布局里追加一列面板。顺序决定了从左到右的排列。想调整布局，移动调用顺序就行。

面板类型

目前内置了这些面板：

• add_text() / fp_text() — 纯文本列，支持对齐、缩进、格式化函数
• add_text_ci() / fp_text_ci() — 把 est/lower/upper 三列自动格式化成 “0.45 (0.32, 0.61)”
• add_ci() / fp_ci() — 置信区间可视化，支持对数刻度、截断箭头、菱形汇总、favors 标注
• add_bar() / fp_bar() — 水平柱状图
• add_dot() / fp_dot() — 散点 + 误差线
• add_gap() / fp_gap() — 固定宽度间距
• add_spacer() / fp_spacer() — 绝对单位间距（mm）
• fp_custom() — 自定义面板，传入一个返回 ggplot 的函数

不够用的时候，fp_custom() 加上 fp_register() 可以注册自定义面板类型，引擎会自动纳入渲染流程。

列驱动的美学映射

跟 ggplot2 的 aes() 思路类似，panelforest 用 fp_aes() 把数据列映射到视觉属性：

1
2
3
4
5
6

# 数据里有 ci_colour 和 ci_shape 两列
forest_plot(df) |>
  add_ci("OR", "LCI", "UCI",
    mapping = fp_aes(colour = "ci_colour", shape = "ci_shape")
  ) |>
  fp_render()

这样每一行可以有不同的颜色和形状，不需要手动逐行设置。

统一的 edit() 编辑层

想给某些行做特殊处理？一个 edit() 函数搞定行级、单元格级、行高调整：

1
2
3
4
5
6
7
8
9
10

forest_plot(df) |>
  add_text("label", header = "Subgroup") |>
  add_ci("HR", "LCI", "UCI", header = "HR") |>
  # 第 1 行用菱形
  edit(row = 1, panel = "HR", glyph = "diamond", fill = "#dbeafe") |>
  # 第 2-4 行斜体
  edit(row = 2:4, fontface = "italic") |>
  # 第 5 行加高
  edit(row = 5, height = 1.5) |>
  fp_render()

panel 参数可以用索引、标题字符串或列名来定位，不需要记面板编号。

跨列分组标题

多个面板可以用 add_header_group() 加父级标题，层级自动推断：

1
2
3
4
5
6

forest_plot(df) |>
  add_text("label", header = "Drug A") |>
  add_text("n_events", header = "Drug B") |>
  add_ci("HR", "LCI", "UCI", header = "HR") |>
  add_header_group("Treatment", panels = 1:2, border = TRUE) |>
  fp_render()

支持多层嵌套——包含其他分组的分组会自动升至更高层。

设计上的一些取舍

为什么基于 ggplot2 + patchwork

每个面板本质上是一个独立的 ggplot 对象，最终用 patchwork 横向拼接。这个选择有几个好处：

• 继承 ggplot2 的渲染质量和主题系统
• 每个面板的坐标系独立，CI 面板可以用对数刻度，文本面板用 [0, 1] 坐标，互不干扰
• patchwork 的布局系统天然支持比例宽度和固定宽度混合
• 输出是标准 ggplot 对象，ggsave() 直接用

缺点是性能——面板多、行数多的时候渲染会慢。但森林图通常几十行到一两百行，这个量级下完全没有问题。

为什么不做 ggplot2 的 geom

另一条路是写 geom_forest() 这样的扩展。我没走这条路，因为森林图的本质是”多列异构面板”，每列的坐标系和渲染逻辑完全不同。硬塞进一个 ggplot 的 facet 或者 annotation 系统里会很别扭。

patchwork 的多面板方案更自然——每列是独立的 ggplot，互不干扰但共享行坐标。

fp_size() 的存在意义

森林图的尺寸应该由内容决定，不应该让用户猜 width 和 height。fp_size() 根据面板数量、行数和行高自动计算出精确的英寸尺寸：

1
2
3

size <- fp_size(plot_obj)
ggsave("forest.png", fp_render(plot_obj),
  width = size["width"], height = size["height"])

这样不管你加几列面板、数据有多少行，出图的密度和比例都是一致的。

CI 面板的细节

fp_ci() 是功能最密集的面板，支持的东西比较多：

• 对数刻度：trans = "log"，自动处理正值约束和刻度标签
• 截断箭头：CI 超出显示范围时，用箭头提示截断方向，箭头类型可配置 (arrow_type = "open" / "closed")
• 菱形汇总：add_summary() 标记的行自动渲染为菱形
• favors 标注：favors_left / favors_right 在坐标轴下方画方向箭头和标签
• 参考线：ref_line 画虚线
• 美学映射：通过 fp_aes() 让每行有不同的颜色、形状、大小

这些功能单独看都不复杂，但组合起来就能覆盖绝大多数临床研究的森林图需求。

一个完整例子

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

library(panelforest)

df <- data.frame(
  label = c("Overall", "Age < 65", "Age >= 65", "Male", "Female"),
  HR = c(0.72, 0.68, 0.81, 0.75, 0.69),
  LCI = c(0.58, 0.49, 0.61, 0.55, 0.48),
  UCI = c(0.89, 0.94, 1.07, 1.02, 0.99)
)

plot_obj <- forest_plot(df) |>
  add_stripe(c("white", "#f4f7f5")) |>
  add_summary(1) |>
  add_hline(1) |>
  add_text("label", header = "Subgroup", width = 2, align = "left") |>
  add_text_ci("HR", "LCI", "UCI", header = "HR (95% CI)", width = 2) |>
  add_ci("HR", "LCI", "UCI",
    header = "Hazard Ratio",
    trans = "log",
    width = 3,
    show_axis = TRUE,
    favors_left = "Favors treatment",
    favors_right = "Favors control"
  )

size <- fp_size(plot_obj)
ggsave("forest.png", fp_render(plot_obj),
  width = size["width"], height = size["height"],
  dpi = 300, bg = "white")

从数据到出图，代码结构很清晰：数据 → 装饰 → 面板 → 渲染。想调整布局就移动 add_*() 的顺序，想改样式就加 edit()。

后续计划

panelforest 目前是 v0.2.0，核心功能已经稳定。后续打算做的事情：

• forest_plot_from() — 模型直出森林图：传入 glm、coxph、lm 等模型对象，自动生成森林图。底层基于 broom::tidy()，根据模型类型自动推断效应量（OR/HR/β）和坐标变换。逐步适配 lme4、metafor、brms 等更多包。
• add_rule() — 条件样式：声明式规则批量高亮，替代逐行 edit()
• 更多坐标变换：sqrt、logit 等
• 文本自动换行、导出助手、脚注系统等体验优化

最重要的是模型直出这个方向——让 panelforest 不只是一个画图工具，而是能直接对接统计建模的输出，减少”跑完模型还要手动整理数据再画图”这个环节。

项目地址：https://github.com/lenardar/panelforest

做数据分析的人，大概率都在 pandas 和 tidyverse 之间摇摆过。

如果你长期写 R，dplyr / tidyr / stringr 那套东西会很顺手：选列有 selector，批量变换有 across()，宽长表转换、字符串处理、缺失值处理都有比较统一的入口。

但一旦切到 Python，虽然 pandas 功能很强，日常清洗时还是经常会冒出几个问题：

• 想按前缀、类型、条件批量选列，不够统一
• 想对一批列做同样的处理，assign(...) 经常要自己手搓字典
• 想把清洗步骤写成稳定、可复用、可读的链，容易堆很多一次性 lambda
• 从 tidyverse 迁移过来时，肌肉记忆没地方放

所以我写了 TidyPy4DS。

它不是想重写 pandas，也不是想做另一个复杂框架，而是只补一小块真正不够顺手的地方：列选择、批量变换、字符串处理、宽长表转换，以及更自然的 .pipe() 链式体验。

项目地址：https://github.com/lenardar/TidyPy4DS

这个项目想解决什么

一句话说，函数名尽量跟 tidyverse，接口行为坚持 Python / pandas。

也就是说：

• 不做 SQL DSL
• 不做惰性执行引擎
• 不替代 groupby、merge、assign 这些已经很成熟的 pandas 原生能力
• 只把最容易重复、最容易写散的那部分动作收成统一入口

目前项目里最核心的几组能力是：

• selector 系统：starts_with、contains、numeric、where 等
• 批量变换：mutate_across
• 批量改名：rename_with
• 汇总：summarize
• 结构查看：glimpse
• 条件映射：case_when、if_else、recode
• 宽长表转换：pivot_longer、pivot_wider
• 缺失值处理：drop_na、fill_na、replace_na
• 表头清理：clean_names、remove_empty、row_to_names

一个简单对比：纯 pandas vs tidypy

先看一份很常见的数据：

1
2
3
4
5
6
7
8
9

import pandas as pd

df = pd.DataFrame({
    "employee_id": [101, 102, 103, 104, 105],
    "dept": ["Sales", "Sales", "Tech", "Tech", "HR"],
    "score_math": [92.0, None, 88.0, 79.0, None],
    "score_eng": [85.0, 90.0, None, 82.0, 87.0],
    "name": [" Alice ", "Bob ", " Carol", "David", " Frank "],
})

目标很普通：

• 只保留 ID、分组、分数字段和名字
• 用每列中位数填补缺失值
• 去掉 score_ 前缀
• 去掉名字前后空格
• 按数学成绩做一个等级
• 最后按分组汇总

纯 pandas 写法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

pandas_result = (
    df.loc[:, ["employee_id", "dept", "score_math", "score_eng", "name"]]
    .assign(
        score_math=lambda x: x["score_math"].fillna(x["score_math"].median()),
        score_eng=lambda x: x["score_eng"].fillna(x["score_eng"].median()),
    )
    .rename(columns={"score_math": "math", "score_eng": "eng"})
    .assign(
        name=lambda x: x["name"].str.strip(),
        level=lambda x: pd.Series(
            ["A" if v >= 90 else "B" if v >= 80 else "C" for v in x["math"]],
            index=x.index,
        ),
    )
)

这段代码当然没问题，而且完全是标准 pandas。

但你会发现几个特点：

• 分数字段被显式写了两遍
• 改名前后的列名都要手动维护
• 当类似列变多时，改动面会越来越大

tidypy 写法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

from tidypy.tidy import (
    case_when,
    clean_names,
    mutate_across,
    rename_with,
    select,
    starts_with,
)

tidypy_result = (
    clean_names(df)
    .pipe(
        select,
        "employee_id",
        "dept",
        starts_with("score_"),
        "name",
    )
    .pipe(
        mutate_across,
        starts_with("score_"),
        lambda s: s.fillna(s.median()),
    )
    .pipe(
        rename_with,
        lambda c: c.replace("score_", ""),
        starts_with("score_"),
    )
    .assign(
        name=lambda x: x["name"].str.strip(),
        level=lambda x: case_when(
            (x["math"] >= 90, "A"),
            (x["math"] >= 80, "B"),
            default="C",
        ),
    )
)

它并不是神奇地比 pandas 少很多代码。

真正的区别在于：你开始把“哪些列属于同一类”和“这批列要做什么”分开表达了。

这个分离在小数据上可能只是“看着顺一点”，但一旦你多加一个 score_logic 列，差别就出来了：

• 纯 pandas 版本通常要改多处显式列名
• selector 版本通常只要让新列符合 score_ 规则，主流程基本不用改

如果再往真实一点的数据走，差异会更明显。比如很多 Excel 导出来的原始表根本不是“干净 DataFrame”，而是：

• 列名里有空格、括号和标点
• 第一行才是真正的表头
• 后面还夹着全空行、全空列

这时候我最近补进去的一批 janitor 风格函数就比较顺手了：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

from tidypy.tidy import clean_names, remove_empty, row_to_names

raw = pd.DataFrame(
    [
        ["Patient ID", "Score Math", None],
        [1, 90, None],
        [2, 88, None],
        [None, None, None],
    ]
)

result = (
    raw
    .pipe(row_to_names, row=0)
    .pipe(remove_empty, axis="both")
    .pipe(clean_names)
)

这类东西单看都不复杂，但它们经常正好卡在“pandas 原生当然能做，只是每次都要重写一遍”的位置上。

核心设计：先把列选择系统做对

这个项目里最重要的抽象其实不是 mutate_across()，而是 ColSelector。

所有 helper 都返回一个 selector 对象，真正操作时再结合 df 解析出列名。

比如：

1
2
3

select(df, numeric() | starts_with("id"))
select(df, everything() - contains("tmp"))
mutate_across(df, where(lambda s: s.isnull().any()), lambda s: s.fillna(0))

这样做有几个明显好处：

• helper 可以访问列名，也可以访问 dtype 或数据本身
• selector 可以组合
• 列选择逻辑可以复用，而不是散落在各处

我最后定下来的规则也比较简单：

• | 表示并集
• - 表示排除
• 结果去重且保序
• 解析不到列时直接报错，不静默忽略

这套东西一旦稳定下来，后面的 select、mutate_across、rename_with、pivot_longer 都会自然顺很多。

一个我刻意没有做的东西：裸列名 NSE

如果熟悉 tidyverse，可能第一反应会问：

能不能做成 mutate(df, total=a + b) 这种效果？

答案是：理论上可以硬做，实际上不值得。

在 R 里，mutate() 这种体验背后是 tidy evaluation；Python 没有这一层语言机制。真要做，只能走 eval、AST 改写、代理对象这些路线。

这种东西最大的风险不是“写不出来”，而是：

• 报错不直观
• 调试很差
• 和 pandas 生态不一致
• 一旦边界复杂起来，很容易变成一套脆弱的语法魔法

所以我最后的取舍是：

• 不做裸列名 NSE
• 保留 assign(...) 处理少量显式新列
• 用 mutate_across(...) 解决批量变换
• 用 case_when(...)、if_else(...)、recode(...) 解决条件映射和重编码

这套方案不花哨，但更稳。

glimpse() 也是我很想要的一个小东西

在 notebook 里，head() 看值，info() 看结构，但两者之间总觉得差一口气。

所以我顺手加了一个 glimpse()：

1
2
3

from tidypy.tidy import glimpse

glimpse(df)

它会给出：

• 行数、列数
• 每列 dtype
• 非空数、缺失数
• 唯一值数量
• 前几条样本值预览

而且支持：

1
2

glimpse(df, cols=starts_with("score_"))
print(glimpse(df, as_text=True, display=False))

这玩意不大，但在实际 notebook 里非常顺手。

现在这个项目是什么状态

目前 TidyPy4DS 已经有一版可以直接用的实现，仓库里也把几件基础设施补上了：

• 双语 README
• 双语函数文档
• 双语 notebook 示例
• unittest 测试
• GitHub Actions CI
• 一批偏 janitor 风格的小函数

示例 notebook 分成了三类：

• Why tidypy：直接对比纯 pandas 和 tidypy
• Core APIs：看 selector、mutate_across、summarize 这些核心能力
• Reshape and missing values：看 pivot_longer、pivot_wider、separate、unite、缺失值处理

项目整体还在早期阶段，但核心方向已经比较清楚：

• selector 系统要稳定
• API 要尽量少而清晰
• 不做多余包装
• 不和 Python 自身的直觉打架
• 单文件实现先保持，但内部已经按模块整理，后续可拆

最后

这个项目本质上不是在和 pandas 对抗，而是在承认一件事：

pandas 很强，但确实有一些高频清洗动作，写起来就是不够顺。

如果能用一层很薄的 helper，把这些动作收成更统一、可复用、可读的入口，那它就值得存在。

如果你也经常在 pandas 和 tidyverse 的思路之间切换，TidyPy4DS 也许会正好补上你手感里缺的那一块。

最近我自己的感受也更明确了：这个项目最有价值的地方，不是“把 tidyverse 完整搬到 Python”，而是把那些每天都会写、但又总写得零碎的数据清洗动作，收成一套尽量干净的小工具。

项目地址：https://github.com/lenardar/TidyPy4DS