Niapya Blog

为了创建一个猫娘我们都做了什么

Wed, 16 Sep 2026 07:10:19 GMT

从 Next.js 到 Nuxt 再到 TanStack Start，5 天内用 Durable Objects、Just Bash 虚拟文件系统、VRM 桌面宠物和自研的 DTP 对话协议，从零搓出一个猫娘 Luna。文章记录了架构选型的取舍、6 小时 Agent 驱动的大规模迁移，以及为什么 Bash 就是 Harness 的全部。

起因

我和我的两个朋友组队，三个人报了知乎的 2026 黑客马拉松。

我们聊了一圈，决定做一个猫娘，她叫 Luna，我们的灵感来自于酒馆式角色聊天🍺，再加上龙虾那种能动手干活的智能体🦐，再配上养成。于是就有了她。

在生活上，他是你的好伙伴，你的每一个爱好，他都会记到他的记忆里，我们认真设计了 LUNA 的记忆系统，下次再见面，她还记得你喜欢什么。

在工作上，他还可以帮你处理一些复杂的程序，你可以添加 agent skill，甚至是上传附件，由它调用 python 去解决。

在娱乐上，她是你的好玩伴，我们做了养成和成就系统：喂她吃饭、给她喝水、帮她清洁，亲密度会慢慢提高。

我们还为 LUNA 做了一个模型，它也会跟着动。她会先想一想，再一条一条地回你，会发贴纸，会做表情，就好像她真的出现在你面前一样。

成品在这里：LUNA，所以为了创建一个猫娘，我们都做了什么？

技术设计

为了做出这个产品，我们下了很多功夫，从架构定型、设计整个 Harness，到前端等等，我们都有慎重的考虑，而且做了很多新东西。

尽管如此，我们这个项目是不到 5 天内做完的，非常仓促。在这期间，我们大概用了 1000 刀的 tokens。

我们从一开始就把它定为一个完整的全栈 Web App，挑选一个前后端一体框架非常重要，我们本项目最开始的架构是 Next.js，是 OpenNext 驱动的 Next.js。但是有很多原因，我们先后迁到了 Nuxt，到最后的 TanStack Start 框架，这一路的心路历程和背后的取舍，待会儿我都会讲到。

基于 Cloudflare Durable Objects 设计的 Agent 架构

我们从一开始就把它定为一个完整的前后端一体 Web App，在最开始这个项目定型之前，我们一直把它部署在 OpenNext 驱动的 Next.js 中，部署在 Cloudflare 上。

我们在第一次开发完成的时候，发现它非常慢，而且 Next.js 的 Adapter API 没有受到 Cloudflare 的支持，所以这让我下定了决心，第一次重构放弃了 Next.js，转向了 Vue 框架的 Nuxt.js，由于 Nuxt 的原语统一了 KV、Database 以及 Blob，所以我们自然选择了 Nuxt。

Cloudflare 与 Vercel 不同，它是一个集大成的东西，偏向基础设施，一个服务掌控了一切，比如有

SQL database：比如说 D1 SQLite
NoSQL database：比如说 Key-Value 的 KV
类 S3 的存储：R2 Blob

我们一开始设计的架构非常简单，而且符合大众的思考，应该把所有的用户数据、会话数据存到 SQL database 中。用户的附件应该存到 R2 的 Blob 中。

但是 Cloudflare 是一家 Serverless 服务商，在 Serverless 这种情况下可能会遇到问题。

第一，与 Supabase 不同，Cloudflare D1 它的服务分布在全球各地，如果我们用的是 D1 的全球副本，数据的复制是异步的。我们在存入数据时，副本可能还没有完成更新，所以读取这些副本会有延迟。

第二，我们 AI 会话的本身需要并发地大量处理各种的状态更新，用 D1 难以保持它的一致性。

所以，这就隐性造成了很多问题，特别是在同步会话和信息时，会造成非常大的隐患。我们尝试过把会话数据以 JSON 或其他格式存在 R2 中，写入时加一个锁来保证一致性，但是 R2 的 IO 开销比较大，而且它毕竟是远程存储，不适合频繁地把整个 Session 读出来、修改、写回。

这个时候我在寻找解决方案时，想到了 Cloudflare 的 Durable Objects。

DO 用 JavaScript class 去描述，有全局唯一的实例身份，同一个 Durable Object ID 在全局同时只会有一个实例运行，并且每个实例都有自己私有的、事务性的、强一致性的持久化存储，还提供完整的 SQLite 存储 API。

export class MyDurableObject extends DurableObject<Env> {
  async sayHello() {
    let result = this.ctx.storage.sql
      .exec("SELECT 'Hello, World!' as greeting")
      .one();
    return result.greeting;
  }
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const stub = env.MY_DURABLE_OBJECT.getByName(USER_ID);
    await stub.sayHello();
  }
}

我们可以把一个用户或者一个会话直接映射成一个 Durable Object，让这个对象本身成为状态的持有者，并负责协调对这个状态的访问。

Durable Objects 以 Serverless 形态运行，按需唤醒，接到请求或者其他 Worker 的 RPC 调用时启动，并在一段时间内销毁。

Durable Objects 还实现了 Alarm，符合我们未来要做的定时任务的需求。

Durable Objects 只有 Cloudflare 才有，所以我们主动放弃了平台无关性，我们分了三层来重新构思这个持久化设计：

第一层是基于 D1 SQLite 的用户和验证：我们使用 Better Auth 和 Drizzle 来完成
第二层是基于 Durable Objects 的用户数据，比如说记忆、定时任务、配置，他们存储在 User DO 的 ctx.storage.sql 中。
第三层是基于 Durable Objects 的会话设计，我们使用 Cloudflare Agents SDK 来完成会话设计

           AI Chat
               │
      ┌────────┴────────┐
      │                 │
     D1                DO
      │                 │
     Auth        ┌──────┴──────┐
                 │             │
               User ──────> Sessions
                 │             │
              State A       State B

这样下来，我们让 SQL 负责相对稳定的全局数据，把真正需要强一致、并发协调的状态交给 Durable Objects。

具体到 Luna，就是两个 DO 各司其职：

UserDO 按用户维度持有记忆、配置、宠物数值、技能清单和文件索引。
ChatDO 按会话维度持有对话历史和模型轮次。

同一个用户或同一个会话在全球同时只有一个实例在运行，并发写冲突由 DO 单例本身协调。

Worker 收到用户消息后唤醒对应的 ChatAgent，ChatAgent 再去 UserAgent 拉取记忆构成 system prompt，然后一边流式调用模型、一边把模型的增量输出翻译成结构化帧落入存储，最后以 SSE 流回浏览器。

使用 Agent 在 6 个小时从 Nuxt 迁移到了 TanStack Start

之前说过，我们项目最开始是用 OpenNext 的 Next.js 来实现的，然后我们迁移到了 Vue 的 Nuxt.js，因为我们看中了 Nuxt Hub 的平台无关性。

但是，当我们确定 DO 架构时，发现 Next.js 并不能真正处理 Cloudflare Durable Objects 的绑定，这是一个 Cloudflare 的已知 issue。

UserDO / ChatDO 在 Nuxt 的适配层里根本拿不到，缺少 DO 绑定就无法继续推进。

所以我们决定：用 Agent 把整个项目从 Nuxt 搬到 TanStack Start。

这次迁移花了大概 6 个小时，思路是分而治之、ReAct 与测试。

第一步，先把依赖的映射关系理清楚。

Nuxt 是一个重度约定的前后端一体框架，字体、图片、UI、内容、动画都有官方模块。我们开了多个 subagent 并行去找 React 生态的对位替代——比如 Nuxt Content 对应 Content Collections，Nuxt Hub 对应 Cloudflare Vite 插件，motion-v 对应 motion，TresJS 对应 React Three Fiber，Nuxt UI 对应 shadcn/ui。React 生态足够大，这一步几乎没有卡点。

第二步，配置 Skills 和 Hooks。

通过 Context7 抓取目标库的最新文档，并用 npx skills find 和 bunx @tanstack/intent 安装官方 Skills，避免 Agent 靠编写错误的 API。

然后我们还配置了 ESLint 和 Prettier，并设置了 hooks，使它在每一步完成后，都能及时地进行类型检查、lint 检查以及格式化检查。

第三步，拆解层级，定好 monorepo 的边界。

Nuxt 的 layers/（按 00.site / 01.auth / 06.chat … 数字前缀决定优先级）被拆成 packages/@luna/*，apps/web 作为唯一可部署的 TanStack Start 应用，其余包只通过子路径导出对外暴露，禁止跨层反向依赖。

Nuxt 的自动发现被显式的 workspace 依赖取代，结构反而更清晰了。

第四步，UI 体系从 Nuxt UI 切到 shadcn。

列出所有用到的组件，逐一映射到 shadcn 的 Components，我们既然都 monorepo 了，就都放在 @luna/ui 子 repo 中。

第五步，主 Agent 列出包含 subagent 顺序计划，开始实现

这一步是关键，由于各种 layer 相互错综复杂，所以我们在制定计划时，必须要考虑 subagent 的顺序，哪一步是并行，哪一步是先后的。

我们必须综合速度和质量，考虑各个 monorepo 的顺序来重构，这样才能重构成功。

最后，启动服务，使用 Chrome MCP 测试。

在 127.0.0.1:3000 拉起开发服务器，用浏览器自动化走一遍完整链路，确认 DO 的 RPC 和 SSE 能够正常连通。

我们没有写任何 codemod 全部由 AI 来搞定，我们使用 Grok 4.6 来做到这一切，6 小时后，已经可以在本地跑通完整的对话链路。

Three.js 与 VRM 的宠物

为了拟人感，也是为了有虚拟现实的体验，我们一开始就打算使用一些模型，比如说 Live2D 或者是 3D 的模型。

这个 VRM 模型是我们队的美术担当花一个下午制作出来的，从 VRoid Studio 捏人、调整骨骼，到导出 .vrm，再到在 Three.js 里点亮，前后大概 4 个小时。

VRM 本质上是带扩展的 glTF，@pixiv/three-vrm 会处理 humanoid 骨骼、人形约束和表情 blendshape。

思路上我们把「渲染」和「状态」分开。

渲染是一个 R3F 场景，负责加载 VRM、计算包围盒自适应相机、混合动画过渡；状态侧是一个小的状态机，管理 idle / happy / sleep 等动作的切换。

为了性能，Three.js 场景只在宠物面板展开时才加载，收起时只保留数值面板。

状态有一套数值系统（饱食度、心情、亲密度），存在 UserDO 里，每次对话结束会微调。

关于动作，我们使用下面要讲到的 Dialogue Transport Protocol 来在会话时执行 VRMA 动作。

在喂食和清洁等操作时，我们还预设了一些动作，我们还在内部维护了一个状态机，在 idle 时也会偶尔执行动作，以免用户无聊。

Bash Tool 就是你 Harness 的全部

然后我们开始设计整个 Harness，在 Agent Loop 就是老的 Pi 的那一套，存储消息，估算 token，达到预算后压缩。

但是我们真正要考虑的是 function calling。

我们每次请求 AI，请求之间的往返是有时间成本的。如果我们把所有的聊天工具、宠物工具以及其他工具都做成 tool， API 的次数会很多，而且会造成很大的时间成本，所以关于这个设计，我们有一个消息协议和三个工具。

协议等会儿我们再讲，我们先说这三个工具。

view：AI 的眼睛，可以通过指定行数来查看大文本，它还支持多模态媒体，比如图片、视频和音频
patch：AI 的手，可以一次性更改多个文件
bash：AI 的心脏，其他所有的功能都会通过 Bash 解决

一个虚拟的 FS

我们希望 Luna 拥有一个“像真实电脑一样”的文件空间，这样他可以参与复杂任务。

有目录、有文件、能安装技能、能保存附件。但 Cloudflare Workers 没有本地文件系统，R2 是对象存储，DO SQLite 也不适合直接存放大块文件内容。

所以我们做了一层虚拟文件系统（VFS），把「索引」和「内容」分开。

索引是一份 manifest，存在 User 的 Durable SQLite 里，记录每个路径对应的对象 key、大小和类型。

真正的文件内容作为不可变对象存在 R2 里，每次写入生成一个新的 UUID key，旧对象由后台任务回收。

目录也做了权限划分，/luna/system 是只读的系统技能，/luna/user/<id>/skills 和 /luna/user/<id>/attachments 才是用户可写的空间，其他路径一律拒绝。

/luna/system
    └── READ ONLY

/luna/user/<id>/
    ├── skills/       ← READ + WRITE
    └── attachments/  ← READ + WRITE

其他路径
    └── DENY

并发则用 CAS（compare-and-swap）保证：每次提交带上预期的版本号，冲突就返回错误并重试，避免两个轮次同时写入把索引破坏。

限制也写得很明确，单文件 5 MiB、最多 100 个文件、总计 20 MiB。

再给一个虚拟 Bash

有了文件系统，下一步就是让 Agent 能使用更加强大的工作，bash 承担 90% 的能力，AI 经过的训练已经包含大部分的 Bash 语料，所以它本身就已经熟悉 Bash。因此，我们需要给 AI 一个 Bash 工具。

但是我们不能真的给 Agent 做一个真实的 Bash。因为有两点：

成本：如果我们每一个对话都给 Agent 分配一个 container，那么成本会很大
安全：如果给他真实的 Bash 环境，那么权限和安全就变得不可控，

所以我们给 Agent 一个虚拟的 Bash，Bash 的运行时是 Just Bash，一个能在 JS 环境里运行的 Bash 模拟器，我们运行在 Cloudflare Workers 里。

它的文件系统就是上面那套 VFS，网络开放了 curl，执行有配额限制，每次对话都在一个隔离的 shell 里执行，不会污染其他轮次。

因为是虚拟 Bash，单一能力的工具就没有保留的必要，我们设计了一个自定义的工厂函数，他可以自定义 command。

比如我们可以设计一个 skill 工具，可以让他搜索和读取 skills。

我们可以给 Agent 添加新功能的方式就是自定义 command + skills 的做法

想让 Luna 记住一件事，直接往文件里追加一行，想安装一个 skill，用 curl 拉取后保存到技能目录，想查询天气、搜索网页、拉取知乎热榜，这些在 Luna 里都注册为 Bash 的自定义命令，既可以在 shell 里以 CLI 形式调用，也可以被模型以工具形式调用——同一套注册表，两套入口。

甚至有些是 client command，部分命令需要浏览器配合，比如获取定位、发送通知、切换主题，它们会通过 ChatDO 的 WebSocket 往返到当前标签页，这种感觉真的很奇妙，这可能就是「人机恋」的魅力吧。

我们把 Harness 做成了文件系统 + Bash，模型学会使用 Bash，就学会了操作 Luna 的整个世界。

介绍我们研发的新协议 Dialogue Transport Protocol

刚才我说了，每一次 AI 的 API 往返都是有时间和价值成本的，所以我希望它一次可以返回多个信息。

我们最开始设计的方案是 JSONL，每一行都是一个独立的 JSON。

{type: "text", content: "hello\nworld"}
{type: "sticker", id: "smile"}

但是我们很快就发现一些问题。既然让 AI 来输出，它的输出就是不稳定的。

比如 JSONL，我们每行都是一个 JSON，看起来实现很方便。但是，所有的换行都需要 AI 主动用转义符转义，AI 很难做到这一点，所以很难解析成功。

所以我们要设计一个全新的协议，需要满足以下条件：

不能与大部分常见的语言重合

因为 AI 输出是不稳定的，我们不能去直接设计成 JSON 或者是 XML 的格式，因为如果我们直接让 AI 去输出代码，它们可能会直接用这些格式，直接会造成格式冲突。

支持多条消息：

AI 直接生成协议文本，我们希望可以包含多个消息、多个事件，而且可以自定义属性。

消息有很多类型，例如文字、图片、语音、视频。

那么事件也有可能包含多个类型，比如反应、投票。

足够熟悉、简单：

门槛不能太高，而且可以容错，例如像 wired HTML 一样，我们即使标签没有闭合，即使它的属性带有引号或者是属性，或者是嵌套错误、重复嵌套，也能够解析。

解析简单

便于跨平台、跨语言迁移。

人类可读

AI 输出的是文本，人类阅读的也是文本。

所以我们设计了我们自己的 frame，我们把它称作 Dialogue Transport Protocol(DTP) 协议。

┌──────────────────────────────────────────┐
│ <|message                                │
│   id=msg_123                             │  ← Header / Envelope
│   type=text                              │
│   reply=msg_100                          │
│   target=user_42                         │
│   ...                                    │
│ |>                                       │
├──────────────────────────────────────────┤
│                                          │
│  Hello!                                  │
│                                          │  ← Payload
│  This is **Markdown**.                   │
│                                          │
│  ```ts                                   │
│  console.log("hello")                    │
│  ```                                     │
│                                          │
├──────────────────────────────────────────┤
│ <|/message|>                             │  ← End
└──────────────────────────────────────────┘

协议长什么样

DTP 的每一帧都是这样的文本——分隔符用 <| ... |>，几乎不会和 Markdown、代码块、HTML 冲突，模型不需要转义就能稳定生成。

帧头是类 HTML 属性的键值对，id / type / reply / target 等信封字段由协议定义，其他字段由具体类型自行扩展。

载荷就是普通的 Markdown 文本。

<|message id=a type=text |>
Hello
<|/message|>

<|message id=b type=sticker |>

<|message id=c type=reaction target=a emoji=❤️ |>

<|message id=d type=vote target=a options="A,B,C" |>

流式解析

模型是逐 token 流式输出的，DTP 提供了流式解析器，每收到一段就喂进去，结束时做隐式闭合和引用解析。

它和批量解析共享同一套词法和语法，行为完全一致。

在 Luna 的对话链路里，流式解析器就夹在模型输出和前端渲染之间，把文本流实时翻译成结构化帧，再分发到 SSE 推送、DO 存储，然后 dispatch。

历史消息先被反序列化为 DTP 文本塞进 system prompt，让模型看到用哪些 id 去回复。

模型生成时，流式解析器把增量文本翻译成帧，并把临时 id 重映射为服务端稳定 id。

最后根据帧类型发送前端，然后分发出对应的消息和事件。

整个过程对前端是透明的，收到的就是一条条带类型的消息。

尾声

5 天 3 个人花了 1000 刀 tokens做了一个我们的 OC 猫娘，路程真的是艰辛。

为了强一致的会话，我们放弃了平台无关性，选择 all-in Cloudflare Durable Objects。
为了让 Harness 足够通用，我们放弃了一堆零散的工具，只保留 Bash。
为了让协议满足需要，我们放弃了 JSON，选择了我们设计的消息协议。
为了让架构真正跑通，我们放弃了 Nuxt 的舒适区，用 Agent 在 6 小时内搬完了整个应用。

这些取舍让 Luna 拥有了自己的文件系统、自己的身体、自己的记忆和技能，以及自己的通信协议。

如果你也想养一只 Luna，欢迎来 luna.htu.me/chat 找她聊天。

它开源在 LUNA 中。

迁移到 remix@3

Wed, 29 Jul 2026 21:24:00 GMT

迁移到 Remix v3 后，我们发现它抛弃了 React，改用自研的 TypeScript UI 框架和显式的 Islands 模型，默认在服务器生成完整 HTML，仅在标记为 clientEntry 的组件中才会注入 JavaScript。借助 Remix 内置的 TypeScript/JSX loader 与 asset server，实现了“无构建步骤”的按需 ESM 加载，同时配合 Twind 动态生成 Tailwind CSS、Satori + Resvg 生成 SVG/PNG 动态图片，让交互可以完全依赖原生表单或视图过渡。尽管框架仍在 Beta、生态尚不成熟，需要自行编写中间件并适配部署平台，但作者认为 Remix v3 已经能够在保持类型安全、组件化与渐进增强的前提下，实现无需 bundle 的现代 Web 应用，并计划继续关注其发展。

最近，我们把这个博客迁移到了 remix@3。

Remix v3 不是 Remix v2 的一次常规升级，它抛弃了 React，之后自己做了一个全栈框架。它仍处于 Beta 阶段，API 和生态都很年轻。

我决定在这么早的阶段使用 Remix v3，是因为我真的喜欢它，它回归到了 Web API 的本质。

一瞥 Remix v3

Remix v3 最引人注目的是没有用 React ，而是重写了一套 TypeScript UI 框架。

Remix 组件不是 React 组件，也没有 Hooks。组件接收一个 handle，然后返回真正的渲染函数。

function Greeting(handle: Handle<{ name: string }>) {
  return () => <p>Hello, {handle.props.name}</p>;
}

状态更新、事件、服务端渲染和水合都围绕这套模型展开。页面默认在服务器上生成 HTML；只有被 clientEntry() 明确标记的组件，才会成为浏览器里的 JavaScript 边界。服务端会为这些边界留下标记并序列化 props，浏览器中的 run() 再按需加载对应模块并完成水合。比如一个计数器可以显式声明为 client entry：

export const Counter = clientEntry(
  import.meta.url,
  function Counter(handle: Handle<{ initialCount: number }>) {
    let count = handle.props.initialCount;

    return () => (
      <button
        mix={on("click", () => {
          count++;
          handle.update();
        })}
      >
        {count}
      </button>
    );
  },
);

这里的 import.meta.url 是服务端源码地址，比如 file:///app/components/counter.tsx。SSR 遇到这个组件时会调用 resolveClientEntry()，把源码地址交给 asset server，换成浏览器能访问的 URL：

const stream = renderToStream(<App />, {
  async resolveClientEntry(entryId, component) {
    return {
      href: await assetServer.getHref(entryId),
      exportName: component.name,
    };
  },
});

服务端仍然先输出按钮的 HTML，但会使用注释标记它拥有的 DOM 区域，大致类似下面这样：

<!--rmx:h:counter-1-->
<button>0</button>
<!--/rmx:h-->

<script type="application/json" id="rmx-data">
{
  "c": {
    "counter-1": {
      "moduleUrl": "/assets/app/components/counter.tsx",
      "exportName": "Counter",
      "props": { "initialCount": 0 }
    }
  }
}
</script>

上面的 HTML 是为了说明协议而简化的，但关键结构来自 Remix runtime：一对 rmx:h 注释负责划定水合区域，rmx-data 保存模块地址、export name 和可序列化的 props。即使 JavaScript 还没有下载，用户已经能看到服务器输出的按钮。

接着浏览器入口启动 run()。runtime 读取 rmx-data、遍历注释标记，并把每个 moduleUrl + exportName 交给 loadModule()：

const app = run({
  async loadModule(moduleUrl, exportName) {
    const module = await import(moduleUrl);
    return module[exportName];
  },
});

await app.ready();

此时才发生真正的网络请求：浏览器执行 import("/assets/app/components/counter.tsx")时 asset server 从磁盘读取 TSX，用 Oxc 解析和转换语法，再把文件里的 import 改写成公开 URL。

浏览器拿回的是标准 ESM，loadModule() 取出其中的 Counter export，runtime 用序列化 props 重建虚拟节点，最后在两条注释之间 hydrate 已有 DOM，并挂上 click listener。相同模块的加载还会被缓存，页面上有十个 Counter 也不会请求十次。

你可能开始感觉有点复杂，但这是一套真正显式的 Islands 架构，不是先把整棵组件树变成客户端应用，再想办法减少 JavaScript，而是默认没有客户端组件，只有确实需要交互的地方才去添加岛屿。

不仅如此，在 AI 时代，Remix 写了一切。remix/data-schema 提供了类似 Zod、Valibot 的 schema、检查、转换和 parseSafe()，它也支持 Standard Schema，所以不得不佩服 Remix 的胆量。

最简单的对象验证很像其他 schema library，schema 本身同时描述了运行时约束和输出类型：

import * as s from "remix/data-schema";
import { email, minLength } from "remix/data-schema/checks";

const User = s.object({
  name: s.string().pipe(minLength(2)),
  email: s.string().pipe(email()),
  role: s.defaulted(s.string(), "reader"),
});

const user = s.parse(User, {
  name: "Ada",
  email: "ada@example.com",
});

最后，它遵循 Standard Schema。s.parse() 和 s.parseSafe() 不只接受 Remix 自己的 schema，也能接收 Zod、Valibot 或 ArkType schema。

除此之外，Remix 还提供路由、中间件、会话、认证和 data table 等一系列彼此配合的包。所有能力都从 remix/<subpath> 导入，边界非常清楚。

Why should we have a build step?

Remix v3 的另一个激进选择，是不把 build step 当作应用运行的前提。

Remix 自己写了一个 TypeScript/JSX loader，在 Node.js 中，可以通过 --import flags 使用。

node --import remix/node-tsx ./server.ts

remix/node-tsx 会在模块被 Node 执行前转换 .ts 和 .tsx。

有人就问了，那浏览器呢？浏览器肯定不能运行 TypeScript 的代码，Remix 的解决办法很巧妙。

需要客户端 JavaScript 时，Remix 的 asset server 可以从源码提供模块、改写 import，并生成 preload 和带指纹的 URL。比如可以把源码目录映射为 /assets 下的公开地址：

import { createAssetServer } from "remix/assets";

const assetServer = createAssetServer({
  rootDir: process.cwd(),
  basePath: "/assets",
  fileMap: {
    "/app/*path": "app/*path",
    "/npm/*path": "node_modules/*path",
  },
  allow: ["app/assets/**", "node_modules/**"],
  deny: ["app/**/*.server.*"],
});

router.get("/assets/*", ({ request }) => assetServer.fetch(request));

当浏览器请求一个 TSX entry 时，asset server 才转换这个模块，并把它依赖的 import 改写成浏览器可以继续请求的 URL。

allow 和 deny 同时构成安全边界，避免服务端文件意外暴露。它仍然会做编译，但不需要提前运行一次 build，也不需要生成和部署一个 dist 目录。

它内部直接组合了 Oxc parser、transform、minifier 和 resolver，再用 es-module-lexer 改写源码、Lightning CSS 处理样式。

更惊喜的是 fileMap 不只可以映射 app/，也可以把 node_modules/ 放进同一张依赖图：

fileMap: {
  "/app/*path": "app/*path",
  "/npm/*path": "node_modules/*path",
}

假设 Counter 里写了 import { on } from "remix/ui"，asset server 会解析这个裸 specifier，找到 node_modules 里的真实 package export，再把它改写成类似 /assets/npm/remix/ui/index.js 的浏览器 URL。浏览器请求这个 URL 时，asset server 继续读取、分析并返回它；依赖还可以继续引用自己的依赖。整个 node_modules 不是被预先塞进一个 bundle，而是像源码一样按 ESM 依赖图按需加载。

getPreloads() 还可以提前遍历这张图，把将要请求的模块变成 <link rel="modulepreload"> 或 Link header：

const preloads = await assetServer.getPreloads([
  "app/components/counter.tsx",
]);
// /assets/app/components/counter.tsx
// /assets/npm/remix/ui/index.js
// ...它们继续依赖的模块

这就是很 amazing 的地方，它保留了浏览器原生 ESM 的请求模型，同时仍然能执行 TypeScript 转换、package resolution、preload、source map、minify 和 fingerprint，却没有要求我们先产出一个 bundle。

准备事项

其实，我认为原生的 Web API 已经足够强大，我们完全可以依赖原生来实现一切。对此，我为新首页设置了几个目标：

没有客户端 JavaScript 参与

博客本来就是一个轻量的程序，所有页面都可以是静态的，没有客户端 JavaScript 参与，顶多在评论时使用表单，这部分完全可以用 HTML 来解决。
没有构建流程

Remix 的 dev 脚本、start 脚本都没有用到构建流程，所以我们也不想添加一个，我想要直接 push 到远程仓库，直接可以运行。
实现一个博客的全部功能

一个博客应该有统计、评论、验证码等功能，应该有一个好的 UI 和 UX，有一个 TOC，以及很好的交互效果。

当应用不再依赖传统 bundler，过去由构建工具顺手完成的事情就需要重新设计。为了保留 Tailwind 的开发体验、流式 SSR 和动态图片，我们做了几项额外工作。

用 Twind 为 SSR 生成 Tailwind CSS

这个项目使用 Twind 的 Tailwind preset，而不是运行 Tailwind CLI 扫描源码并生成一份静态 CSS。Twind 可以读取最终 HTML 中出现的 class，并按需生成对应样式，这很适合没有构建步骤的服务端应用。

问题在于 Remix 返回的是流，而不是一个完整字符串。为此我们写了一个 twind() 中间件：

export function twind(): Middleware {
  return async ({ request }, next) => {
    const response = await next();

    /* ... */

    return new Response(
      response.body.pipeThrough(new TwindStream(), {
        signal: request.signal,
      }),
      { status: response.status },
    );
  };
}

它先等待下游完成 SSR，只处理 text/html 响应，然后把 response.body 接入一个 TransformStream。流中的 HTML 会交给 Twind consume() 扫描，首个文档片段生成的 CSS 被注入 <head>。

如果后续 Remix Frame 又流式返回了新的 class，中间件会比较前后两份样式，只把增量补丁写回页面。关键部分是给每一段流维护独立的 Twind 快照：

const restoreGlobalState = tw.snapshot();
restoreCurrentState();

let html = consume(buffer, tw);
const nextStyle = stringify(tw.target);

restoreCurrentState = tw.snapshot();
restoreGlobalState();

if (lastStyle === null) {
  html = html.replace(
    "</head>",
    `<style data-twind>${nextStyle}</style></head>`,
  );
} else {
  const styleDiff = getStyleDiff(lastStyle, nextStyle);
  if (styleDiff.length) html = createStylePatch(styleDiff) + html;
}

保存和恢复全局快照很重要，因为 Twind 的实例是进程级的，而 SSR 请求会并发发生。每个响应都应该只看到自己的 class，不能把另一个请求刚生成的规则混进来。首次 flush 把完整样式放入 <head>；后续 flush 只发送插入位置和新增 CSS，由一小段内联脚本修补同一个 <style>。

它没有破坏流式渲染，浏览器仍然可以尽快收到文档外壳，后续片段也能获得正确样式。

与此同时，我们仍可使用 Tailwind 风格的原子类、Typography、Autoprefixer、主题 token 和暗色模式，不需要额外的构建命令。

Satori 生成验证码

Satori 是 Vercel 开源的 JSX/对象到 SVG 渲染器。它不是浏览器截图工具，不需要启动 Chromium，而是在服务端根据布局对象和字体数据直接计算出 SVG。我们再用 Resvg 把 SVG 栅格化成 PNG。

最直接的用途是动态 Open Graph 图片。本站会先使用 remix/data-schema 限制 URL 中标题的长度，再把中英文字体显式交给 Satori，最后返回 PNG：

const parsed = s.parseSafe(
  ogImageQuerySchema,
  new URL(request.url).searchParams,
);
const title = parsed.success ? parsed.value.title : "";

const svg = await satori(createCard(lang, title), {
  width: 1200,
  height: 630,
  fonts: [
    {
      data: RENDER_FONT_DATA.instrumentSerif,
      name: "Instrument Serif",
      weight: 400,
    },
    {
      data: RENDER_FONT_DATA.notoSerifSc,
      name: "Noto Serif SC",
      weight: 400,
    },
  ],
});

const png = new Resvg(svg).render().asPng();

const body = png.buffer.slice(
  png.byteOffset,
  png.byteOffset + png.byteLength,
) as ArrayBuffer;

return new Response(body, {
  headers: {
    "Cache-Control": "public, max-age=3600, stale-while-revalidate=86400",
    "Content-Type": "image/png",
    Vary: "Accept-Language",
  },
});

这很简单对吧？我们实现了首页以及每个博客的 OG image，不过更有意思的是评论验证码。

服务端随机生成一组不同颜色和形状的图形，并选定其中一个目标。Satori 和 Resvg 把挑战渲染为图片，目标位置和一次性 token 则保存在 Deno KV 中。页面使用原生 HTML：

<input type="image" name="captcha" src="..." />

用户点击图片后，浏览器会随普通表单一起提交 captcha.x 和 captcha.y，这是 <input type="image"> 原生定义的行为。

服务端只需要用 remix/data-schema/form-data 验证 token 与坐标，再判断点击位置是否落在目标图形附近。challenge 带有短 TTL，并在提交后原子删除，因此同一个答案不能重复使用。

这里真正有意思的不是验证码算法，而是实现思路，Satori 负责生成挑战，Deno KV 保存短暂状态，原生 image input 负责收集点击坐标，普通 HTTP form 负责提交。整个流程没有事件监听、fetch() 或任何 client-side JavaScript。

迁移工作

为了实现我定的那几个目标，实现思路已经很明确了，就是全部使用 SSR 服务器端渲染。

TypeScript / TSX + Markdown
        ↓
    runtime
        ↓
 Remix 流式 SSR
        ↓
Twind 注入 CSS + Satori 生成图片
        ↓
   HTML / CSS / HTTP

押注 SSR 渲染

Remix 的 JSX runtime 来自 remix/ui，他自身做的真的很多。

路由需要先在 app/routes.ts 中声明成一份带类型的 URL 契约。

export const routes = route({
  home: "/",
  blog: route("/blog", {
    index: get("/"),
    article: get("/:slug"),
    comment: post("/:slug/comments"),
  }),
});

再由 controller 返回标准 Response。

export default createController(routes, {
  actions: {
    home({ get, render }) {
      const i18n = createI18n(get(LangContext));
      return render(<Home i18n={i18n} />);
    },
  },
});

render() 最后调用 renderToStream()，得到的可以直接放进 Response 的 ReadableStream<Uint8Array>。

Deno.serve((request) => router.fetch(request));

GET、POST、重定向、语言协商和错误响应都在同一条 HTTP 链路里完成。

评论表单验证失败时，还能让 controller 重新渲染带错误信息的页面，成功时则返回重定向。

这里没有一套服务端模板再加一套客户端状态，HTML 就是状态的最终表达形态。

CSS 新属性注入活力

最近几年，浏览器加入了很多过去必须依赖 JavaScript 才能完成的能力。对这个项目最有用的是跨文档 View Transitions 和 Scroll-driven Animations。

既然我们没有客户端 JS，所以这必须是个 MPA，而不是 SPA。

页面间导航仍然是普通的 <a> 和完整文档请求，但通过 @view-transition { navigation: auto; }，浏览器可以为跨文档导航提供 View Transitions。

比如博客列表与文章页为标题设置相同的 view-transition-name，于是两次独立的服务端响应也能形成连续的视觉过渡。

export function blogPostTitleTransitionName(slug: string) {
  return createDomId("blog-post-title", slug);
}

<h1
  style={{
    viewTransitionName: blogPostTitleTransitionName(post.slug),
  }}
>
  {post.title}
</h1>;

列表页的 <h2> 与文章页的 <h1> 使用同一个稳定名称。浏览器在两次 document navigation 之间为旧标题和新标题建立对应关系，整个过程不需要 SPA router。

我们还在文章内部实现了由 scroll-driven animation 驱动的阅读时间线。

我们先简单封装了一个 ScrollDrivenAnimation 组件。

export function ScrollDrivenAnimation(
  handle: Handle<ScrollDrivenAnimationProps>,
) {
  const {
    timeline = "view()",
    range = "entry 0% cover 40%",
    keyframes,
  } = handle.props;

  const animationStyle = css({
    animationName: `scroll-${handle.id}`,
    animationDuration: "1ms",
    animationFillMode: "both",
    animationTimeline: timeline,
    animationRange: range,
    [`@keyframes scroll-${handle.id}`]: keyframes,
  });

  return () => <div mix={animationStyle}>{handle.props.children}</div>;
}

文章容器声明一个命名的 view timeline，每个刻度按照自己在全文中的百分比消费其中一段进度：

const articleTimelineStyle = css({
  viewTimelineAxis: "block",
  viewTimelineName: "--article-reading",
});

<ScrollDrivenAnimation
  timeline="--article-reading"
  range={`cover 40% cover 60%`}
  keyframes={{
    from: { color: "var(--border)" },
    to: { color: "var(--foreground)" },
  }}
>
  <span data-timeline-line />
</ScrollDrivenAnimation>;

我们根据 Markdown 各节的字数计算。长章节占据更长的时间线，标题刻度同时是普通锚点链接，所以它既是阅读进度，也是一份不依赖 JavaScript 的 TOC。

i18n 也放在请求边界完成。locale() 中间件先读取 URL 的 ?lang=，没有显式选择时再解析 Accept-Language 及其 q 权重，然后把语言写入类型化的 LangContext：

export function locale(): Middleware {
  return (context, next) => {
    context.set(LangContext, getLangFromRequest(context.request), {
      property: "lang",
    });
    return next();
  };
}

这个值不只决定正文文案，还同时决定 <html lang>、日期 locale、OG locale、manifest URL 和动态 OG 图片中的字体。

语言信息从一个请求事实向下传递，不需要浏览器启动后再修正页面，因此首屏 HTML 对搜索引擎和读屏软件也是完整的。

关于 a11y，使用新 Web 能力并不意味着忽略兼容性。

View Transition 与滚动动画都是渐进增强，支持它们的浏览器得到更连贯的体验，不支持时仍然保留普通跳转、锚点和内容。

与此同时 prefers-reduced-motion 则直接关闭动画，让系统设置成为最终决定。

部署

没有构建步骤带来了更直接的开发与部署模型，也让运行平台的差异变得无法回避。

我们先后考察了 Cloudflare Workers、Vercel 和 Deno。

Cloudflare Workers

Workers 是优秀的边缘运行时，但它不是传统服务器环境。应用代码需要被打包成 Worker 可部署的模块，运行时也没有可供应用任意读取的本地文件系统。

对于许多应用，这是合理限制，对于这个博客，却意味着必须在部署前把 Markdown、字体和其他源码资产收集进 bundle，或者迁移到外部存储。我们希望仓库 push 后就能直接运行，文章仍然是磁盘上的 Markdown，运行时能够读取项目文件。

因此 Workers 与这次迁移最核心的 buildless 目标并不匹配。

Vercel

Remix 官方为 Node 准备的 buildless 路径依赖 node --import remix/node-tsx。

在我们考察的 Vercel 托管函数运行入口中，无法为 Node 进程自由追加这类启动 flag，也就不能按照 Remix 推荐的方式直接把 TS 和 TSX 源码作为服务端入口运行。

当然，可以增加一次构建，加上 esbuild 这种构建流程，把代码转成平台期望的产物，但那等于重新引入我们刚刚移除的步骤。

因此这一次也没有选择 Vercel。

Deno

Deno 最终成为最自然的答案。它原生执行 TypeScript 和 TSX，不需要 Node 的 --import loader。

现在的 Deno 也不再是特立独行。它能够直接使用 npm 包，提供成熟得多的 Node 兼容层，同时支持 WebAssembly、Deno FFI 和 Node-API 的 .node 原生 addon。

{
  "tasks": {
    "start": "deno run --allow-env --allow-ffi --allow-read --allow-net deno.ts"
  }
}

这个项目因此可以同时运行 Remix、Twind、Satori 和依赖 .node 原生 addon 的 Resvg，并用 Deno.serve() 接收请求、用 Deno KV 保存评论与一次性验证码。

再加上足够个人站点使用的免费额度，Deno 让这套架构保持了它原本的形状。

源码就是应用，没有生成目录，没有必须提交或上传的 bundle，也没有为了适配平台而额外维护一套方式。

总结

迁移到 Beta 框架当然有代价。

文档、API、生态和部署经验都在快速变化，我们没有成熟的生态，所以需要自己阅读源码、编写中间件。

但是 Remix 3 考虑到了这一点。如今 AI 的发展，Remix 3 的库所有都是 TypeScript 文件，这使得 Remix 3 是对 Agent 友好的，而不是像 Next.js 加一堆编译器魔法，尤其是 use client 这样的 Directive。

而且它没有像 Next.js 那样自己实现一个 PPR 协议，而是从 Web API 本身出发去构建，而且做到了路由、服务器、组件、数据边界和渐进增强的效果。

你可以使用 Islands、Frame 和客户端水合，也可以像这个网站一样，一个 client entry 都不创建。

Remix v3 还很新，我们也仍在继续看它的发展，但是说明了现代 Web 应用自己本身可以拥有类型安全、组件化、动态图片和交互，同时把服务器、浏览器与开放标准放在最中心的位置。

如何构建一个无服务器 Agent

Mon, 27 Jul 2026 03:25:00 GMT

ClawLess 通过 Vercel Workflow 将 Agent 的运行时设为 Serverless，只在收到消息、Webhook 或定时任务时唤醒，从而实现低成本、无需长期在线的服务器。文章阐述了使用 Next.js、Vercel AI SDK、Workflow hook 与 DurableAgent 组合，实现可挂起、持久化的对话流、上下文压缩与工具调用等功能。通过 KV、Blob、Postgres Vector 等存储以及 Bash 沙箱、记忆、技能等工具，构建了既可交互又具扩展性的完整 Agent。作者认为，这种基于 Workflow 的 Serverless 方案是构建持久且成本友好的 AI Agent 的最佳路径。

4 月初，我们开源了 Serverless 项目 ClawLess，它可以在你的 Vercel 账户上免费部署一个 24 小时可用的轻量 Agent。

这篇文章想记录的是 ClawLess 背后的取舍：为什么它应该是 Serverless 的，以及我们如何用 Vercel Workflow、Vercel AI SDK、Vercel Sandbox、KV、Blob 和 Postgres Vector 组装出一个能工作的 Agent。

起因

构建一个完整、长期在线的 Agent 运行时，成本其实不在模型，而在一直运行。

模型你可以选择低价或者免费的模型，但你仍然需要一个自己的服务器、VPS，或者一台长期在线的 Mac mini。

有些项目已经提出了另一种解决方案：使用更小的原生语言重写运行时，把内存占用压低，让它可以运行在树莓派、开发板，或者更便宜的 Linux 设备上。

他们至少需要一个长期在线的设备来运行 Agent，维护它的状态，等待用户消息，处理定时任务，而 ClawLess 一开始就不是这个方向。

对大多数人来说，Agent 最常见的入口仍然是 chatbot：用户发送消息，Agent 读取上下文、调用工具、返回结果。它不需要每一秒都在 CPU 上运行，它只需要在被唤醒时可靠地处理请求。

我们只需要在它接收到会话的时候处理请求即可：

如果是在网页上，那就是在用户发送消息时触发的 API 请求。
如果连接你的 IM，那就是 IM 在收到请求时触发的 webhook，也可以是 API 请求。

除此之外，我们还需要定时任务和延迟任务。比如「明天提醒我继续这个话题」，或者「每天早上把某个 channel 的信息整理一下」。这类任务本质上不要求常驻进程，只要求平台能把某个 workflow 暂停、等待，并在合适的时间继续。

老朋友都知道我比较喜欢 Serverless。它的核心是请求进来时启动，任务挂起时休眠，时间到了再恢复。

由于这种特性，Serverless 服务平台可以以非常低的价格部署，特别是对于 JS Rutime 的，比如 AWS Lambda、Vercel、Cloudflare Workers，而且很多平台都有足够尝鲜的 free tier。

经过调研，我看上了 Vercel Workflow。它可以启动长时间任务，可以在 Workflow 里等待，也可以在特定时间继续执行，因此 ClawLess 可以被消息、Webhook、工具审批和 schedule 唤醒的 Workflow。

换句话说，ClawLess 并不需要你一直运行，只需要按需唤醒。这恰好是 Workflow 这类运行时擅长的事情。

设计

因为同时有前后端，这是一个全栈项目。

对于全栈，我们曾尝试过使用 Nuxt，或是 Hono SSR 的方式来构建全栈，但我们采用 Next.js 来作为全栈框架，因为我们要使用 Vercel Workflow 的 API 来构建 Agent，而 Next.js 是 Vercel Workflow 的原生支持框架。

Workflow 是 Agent 的运行时

我们先谈一下 Vercel Workflow，它是 Vercel 最近推出的官方、长时间运行的、带有状态的流程运行框架。经测试，一个 workflow 能运行至少 10 分钟以上。

我们在做 ClawLess 的时候，Vercel Workflow 还是处于 Beta 阶段，但是现在 API 已经稳定。

它使用 "use workflow"; 和 "use step"; 指令来定义一个 workflow。

use workflow 负责“编排”，也就是跨步骤的状态、等待、恢复和整体流程。
use step 负责“执行”，也就是可以单独重试、适合封装副作用的原子操作。

对于 Agent 来说，真正调用数据库、第三方 API、Sandbox 命令的逻辑，通常放在到 step 里；而等待用户消息、等待审批，比如等待明天早上 9 点继续执行的逻辑，则更适合留在 workflow 这一层。

一个 Workflow 的例子如下：

async function updateUser(userId: string) {
  "use step";
  await db.insert({ id: userId });
}

export async function userOnboardingWorkflow(userId: string) {
  "use workflow";
  await updateUser(userId);
}

export async function POST() {
  await updateUser("123");
}

然后对于 AI 来说，毫无疑问，TypeScript 最流行的 AI framework 是 Vercel AI SDK。

import { convertToModelMessages, streamText, type UIMessage } from "ai";

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: "anthropic/claude-sonnet-4.5",
    system: "You are a helpful assistant.",
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse();
}

然后在前端，你可以使用 useChat 这个 Hook 来轻松地实现一个聊天界面。

"use client";

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
import { useState } from "react";

export default function Page() {
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: "/api/chat",
    }),
  });
  const [input, setInput] = useState("");

  return (
    <>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === "user" ? "User: " : "AI: "}
          {message.parts.map((part, index) =>
            part.type === "text" ? <span key={index}>{part.text}</span> : null
          )}
        </div>
      ))}

      <form
        onSubmit={(e) => {
          e.preventDefault();
          if (input.trim()) {
            sendMessage({ text: input });
            setInput("");
          }
        }}
      >
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          disabled={status !== "ready"}
          placeholder="Say something..."
        />
        <button type="submit" disabled={status !== "ready"}>
          Submit
        </button>
      </form>
    </>
  );
}

useChat Hooks 还提供了 Vue, Svelte 和 Angular 的库。

这已经能完成一个很好用的 Web Chat。但它还不是我们要的 Durable Agent，因为请求中断/结束之后，运行时也就跟着结束了。

这与我们 Agent 的逻辑不同，我们希望在请求中断后还能继续运行，并且在运行后持久化以保存状态。

所以我们的 Workflow 配备了 AI 模块，它和 AI SDK 深度集成，并提供了更适合 workflow 场景的 DurableAgent。

Workflow 的 getWritable() 可以拿到一个持久化的输出流，客户端断开以后还能重新连接回来，继续接收之前没看完的内容。

下面这段是一个简化示意：

import { DurableAgent } from "@workflow/ai/agent";
import { getWritable } from "workflow";
import type { UIMessage, UIMessageChunk } from "ai";

export async function chatWorkflow(messages: UIMessage[]) {
  "use workflow";

  const writable = getWritable<UIMessageChunk>();
  const agent = new DurableAgent({
    model: "anthropic/claude-sonnet-4.5",
    system: "You are a helpful assistant.",
  });

  await agent.stream({
    messages,
    writable,
  });
}

这时候，Agent 才真正开始像一个自主的系统。

在 ClawLess 中，我们的过程更加复杂，主 workflow 会从 KV 读取当前配置，构建 system prompt，从 MCP 加载工具，创建 DurableAgent，然后把输出写到 UI message stream，并且持久化，最后再把状态保存到 Postgress SQL 中。

Hook 让 workflow 真正可交互

考虑更多，比如用户在网页继续发消息，或者 IM webhook 继续发消息时，如果 workflow 还在运行，我们应该去引导（Follow-up）Agent 处理这些消息，而不是直接发起新的 workflow。

这是 Human in the Loop 的基本逻辑。如果你想了解更多，你可以看 WikiPedia 中的 HITL, Human-in-the-Loop.

庆幸的是，Workflow 提供了 hook 来做到这些。hook 的价值是：它允许一个正在运行的 workflow 暂停在某个位置，等外部事件到来之后再继续。

最简单的外部事件就是“下一条用户消息”：

import { defineHook } from "workflow";

// 定义一个 hook，用于接收外部事件（下一条用户消息）
export const messageHook = defineHook<{
  text: string;
  userId: string;
}>();

export async function conversation(sessionId: string) {
  "use workflow";

  const events = messageHook.create({
    token: "chat-" + sessionId,
  });

  // 等待外部事件（下一条用户消息）
  for await (const event of events) {
    console.log("Received", event.text, "from", event.userId);
  }
}

export async function POST(req: Request) {
  const data = await req.json();

  await messageHook.resume("chat-" + data.sessionId, {
    text: data.text,
    userId: data.userId,
  });

  return new Response("OK");
}

同一个机制也很适合做工具审批。比如模型想执行一个高风险命令：删文件、发消息、下单、转账，这时候就不该让它直接运行，而是要把审批请求抛给前端，再等用户确认。

更多信息详见 AI SDK 中关于 Tool Execution Approval 的说明。

Workflow hook 的好处是，你不需要自己轮询数据库，不需要写一套复杂的状态机，因为 workflow 会在等待时挂起，恢复时又从原来的状态继续。

所以，我们总结一下一个 Agent 的顺序：

用户消息进入入口层。
入口层判断当前 session 是否已有活动中的 workflow。
如果有，就用 hook 把新消息送回去。
如果没有，就创建新的 workflow，从头开始处理。

上下文 Context

Agent 有上下文限制（Context Limit）。不同模型的 token 计算方式不同，但它们都有一个共同限制：你必须把 system prompt、历史消息、工具结果、文件输入和记忆都塞进上下文里。

不仅如此，模型在处理长上下文时，正确率也会下降，成本也会增加。

处理长上下文有常见的两种方法，压缩和剪枝。

压缩（Compression）是把“很长但以后还需要”的历史，改写成更短的表示。最常见的做法是：在会话进行到一定长度之后，用模型把早期对话、关键工具结果、已经确认的用户偏好压成一段摘要，然后把原始消息移出当前上下文窗口。

下一轮真正调用模型时，你只需要把摘要重新组装回来。

如果你考虑更多，你可以采用滚动窗口的方法，把摘要和最近几轮的原始消息以及当前输入加进来。

import { generateText, type ModelMessage } from "ai";

export async function compactMessages(messages: ModelMessage[]) {
  const summary = await generateText({
    model,
    messages: [
      ...messages,
      {
        role: "user",
        content: "请总结一下我们之前的对话，提炼出对后续有帮助的关键信息。",
      },
    ],
  });

  return {
    summary: summary.text,
    recentMessages: messages.slice(-8),
  };
}

在 Workflow 里，这种做法尤其自然。因为 workflow 本来就有自己的生命周期和外部存储层，你完全可以在某一轮结束后把摘要写入 KV，把旧消息删掉，只保留一个“会话摘要”字段。这样 durable session 仍然存在，但真正送进模型的上下文不会无限增长。

另一种方法是剪枝（Pruning）。它不试图理解历史，而是直接把“对当前轮次帮助不大”的内容裁掉。

AI SDK 已经提供了 pruneMessages，可以在送进模型之前移除旧的 reasoning、工具调用结果、审批痕迹和空消息。

import { type ModelMessage, pruneMessages } from "ai";

export function buildContextWindow(messages: ModelMessage[]) {
  const pruned = pruneMessages({
    messages,
    reasoning: "before-last-message",
    toolCalls: "before-last-2-messages",
    emptyMessages: "remove",
  });

  const pinned = pruned.filter((message) => message.role === "system");
  const recent = pruned.filter((message) => message.role !== "system").slice(
    -12,
  );

  return [...pinned, ...recent];
}

对于 Workflow AI，通常会在每一轮调用前通过 prepareStep 来重写。

const result = await agent.stream({
  messages,
  writable,

  // prepareStep hook 会在每次调用模型前被调用，用来重写上下文窗口
  prepareStep: async ({ messages: currentMessages }) => {
    return {
      messages: buildContextWindow(currentMessages),
    };
  },
});

这两种方法并不冲突。实际工程里更常见的是组合使用，完全取决于设计。

这是有关 Context Engineering 的概念，你可以阅读 Anthropic 的文章 Effective Context Engineering for AI Agents.

但是，我们还要要考虑的更多，比如说跨对话的请求之间的，同一知识之间的，或者是永久保存的上下文共享，这个时候我们需要引入工具来把它们存储在外部系统里，而不是直接放在模型上下文里。

工具 Tools

Agent 的工具决定了它的能力边界。

如果没有工具，它只是一个聊天模型；有了工具，它才可以保存记忆、执行命令、学习技能、安排任务，甚至把一部分工作交给子 Agent。

在 AI SDK 里，工具本身就是一等公民。一个最小的工具定义大概像这样：

import { tool } from "ai";
import { z } from "zod";

const tools = {
  remember: tool({
    description: "Save a useful fact into long-term memory",
    inputSchema: z.object({
      note: z.string(),
    }),
    execute: async ({ note }) => {
      const memory = await buildMemory(note);
      return { ok: true, memory };
    },
  }),
};

记忆 Memory

记忆是存储长期事实，用户偏好的部分。

你可以把它存储到 KV、数据库，或者以文件形式存储到 Blob，然后给模型添加工具来管理它。

在搜索时，最方便的时全文关键词搜索，但是有很多局限性，比如两个句话关联性强但是没有重叠。

你在公司内部系统搜索“如何处理产假期间的奖金核算”。问题：如果公司制度里使用的是“生育津贴”、“女职工福利”或“长期病假（生育）规定”，而没有同时包含“产假”和“奖金”这两个具体词汇，全文搜索会直接显示“未找到相关结果”，即便系统里实际上有相关的政策文档。

所以，我们可以考虑 RAG, Retrieval-augmented generation, 检索增强生成，这是一种让模型在生成响应时，从外部知识库中检索相关信息的方法。

最简单的是向量嵌入搜索，把一句话通过向量模型映射到一个多维向量上，然后在向量空间中查找最相似的句子。

在查找最相似时，可以使用余弦相似度（Cosine Similarity）的计算方法。

$\operatorname{Similarity} = \hat{\mathbf{q}} \cdot \hat{\mathbf{d}} = \sum_{i=1}^{n} \hat q_i \hat d_i$

将计算出来相似度归一化，之后排序。

在真实系统中，我们一般用混合搜索，也就是将向量搜索和关键词搜索结合起来。

更多关于 Memory 的探究，你可以参考 OpenClaw 的 Memory 设计.

技能 Skills

技能更像基于文件系统的知识库。

一个 Skill 一般存储在文件系统，它目录结构可能是这样的：

my-skill $ tree

my-skill/
	SKILL.md

	scripts/
	templates/
	examples/
	assets/

Skills 表明了怎么做事，比如：

如何写某类测试
如何调用某个内部规范
如何按照团队约定生成代码

我们一般会把 Skills 的标题和描述提取出来，注入到 System Prompt 中。

Skills 是 Anthropic 提出的，具体请看 Agent Skills 概述.

执行 Bash

执行工具是 Agent 真正开始接触外部世界的地方。

一个最基础的执行工具就是 Bash 工具，他可以执行 Shell 命令，它允许了 Agent 和真实环境的连接起来。

在 ClawLess 中，我们使用 @vercel/sandbox 来实现 Bash 工具。

Bash 风险最高，也最需要隔离，要特别考虑工具审核和沙箱环境的隔离。

如果你在寻找 ServerLess 的 Bash 工具或者是需要一个沙箱 Bash 工具，你可以考虑看看我们的 AI SDK X.

任务

在处理复杂的任务时，我们还需要考虑更多。

延时与定时任务

延时任务会在一定时间之后提醒你。

ClawLess 在 Workflow 内部使用 sleep 函数来实现延时任务。

import { sleep } from "workflow";

export async function remindTomorrow(taskId: string) {
  "use workflow";

  await sleep("1 day");
  await sendReminder(taskId);
}

定时任务又称作 Cron Job，它可以让你在指定的时间点执行任务。

定时任务的实现与延时任务相似，我们使用一个 while (true) 循环来实现定时任务。

while (true) {
  await sleep("1 day");
  runTask();
}

子任务 Sub-Agent

子任务不一定非要是另一个完整 Agent，他会把一部分小的任务委托出去。

例如主 Agent 负责和用户对话，但某个研究问题可以单独交给一个更便宜的小模型。

一个最小的 Sub-Agent 实现可以是这样的。

import { generateText, tool } from "ai";
import { z } from "zod";

const delegateResearch = tool({
  description: "Hand off a focused research subtask",
  inputSchema: z.object({
    question: z.string(),
  }),
  execute: async ({ question }) => {
    const result = await generateText({
      model: "openai/gpt-4.1-mini",
      prompt: "Answer briefly and return only key facts:\n" + question,
    });

    return { summary: result.text };
  },
});

MCP 与其他工具

模型上下文协议 (MCP, Model Context Protocol) 是一个统一的协议，他让 Agent 统一接入外部系统的能力。

如果你在做一个特定领域的 Agent，往往更适合 MCP，而不是一堆 Skills。

ClawLess 其实并没有做网页搜索（Web Search），浏览器访问（Browser User）等功能，我们可以通过 MCP 来接入这些能力。

与前端连接

与 Agent 交互的前端部分，我们可以通过网页，Bot 或是其他地方与 Agent 链接。

网页对话

我们刚才的 useChat Hooks 就是最简单的网页对话部分，我们在这里不再叙述。

通过 Webhook 与 IM 连接

大部分即时通讯软件一般会有内置 Bot 的能力，例如 Telegram 、Discord 等。

Bot 大部分只有两种接收消息的方法：长轮询和 Webhook。

长轮询意味着 Bot 需要每隔一段时间（我们称之为心跳周期），向服务器请求最新消息，OpenClaw 的大部分连接器就是这么做的。

Webhook 则是一种更高效的方式，它允许服务器在有新消息时立即通知 Bot，而不需要 Bot 主动请求。

在 ClawLess 内部使用 Chat SDK 来通过 WebHook 连接各个 IM。

Chat SDK 特别简单，只需要你创建一个 Chat 实例。

// Next: lib/bot.ts
import { Chat } from "chat";

const bot = new Chat({
  userName: "mybot",
  adapters: { slack },
  state: createRedisState(),
});

bot.onNewMention(async (thread, message) => {
  await agent.handleMessage(message);
});

然后暴露一个适用于 WebHook 的 API 端口。

// Next: app/api/webhooks/slack/route.ts
export const POST = bot.webhooks.slack;

最后

看到这里，你会发现构建 Agent 的思路其实很简单。

我们特别希望看到你搭配这些，构建自己的 Agent，这真的特别有意思。

另外，我们在构建一个通用的沙盒虚拟 Bash，它适合任何一个 JS Runtime 的环境，以及 ServerLess 和嵌入式，如果你想了解，可以看看我们的 AI-SDK-X 文档.

Welcome To Niapya's Blog

Mon, 27 Jul 2026 03:25:00 GMT

作者认为博客应由作者完全掌控，于是从零实现了一个基于 Hono/JSX 的静态站点生成器，使用 marked 解析 Markdown、UnoCSS 生成原子化 CSS，并在构建时渲染成纯 HTML 文件，从而避免任何客户端 JavaScript。文章展示了内容获取、模板渲染和文件输出的完整流程，并说明了选择轻量化方案的理由。作者计划将该项目发展为完整的框架并提供 UI 组件库、插件化 RSS/Sitemap、表单搜索评论等功能，甚至支持在浏览器中运行。

对，我终于有了一个博客。

2026 年是 Vibe Coding 大火的一年，我们习惯了使用 Code Agent 来编写任何项目，原来的「手搓」代码的方式被调侃为「古法编程」，这个时候大部分人都没有动手习惯了，如果他们希望有一个博客，直接 Vibe 一个 Next.js 模版，甚至直接用现成的 SaaS 博客平台加上 Skills 让 Agent 帮忙写文章就好了。

但是我认为，博客作为自己的平台，理应是由作者掌控一切的，所以我希望可以从无到有做出一个自己的博客框架、自己的博客样式以及博客内容。

制作博客框架

由于这类网站通常不需要服务器端逻辑，我们把博客这类网站称之为「静态网站」，所以我要做的是一个「静态站点生成器」（Static Site Generator，SSG）。

SSG 的流程很简单：获取内容源并解析成文档，使用模板渲染，输出为网站文件，而我希望掌控这一切。

第一步是获取内容源并解析成文档。

内容源的来源可能是任何东西，数据库、CMS、Markdown 文件等等，所以我们创建了一个统一的 Interface，类似于下面。

export function definePost(
  input: {
    title: string;
    category?: string[];
    tags?: string[];
    content: string;
  },
): Post;

这样一来，我们可以在任何地方以任何方式定义我们的内容了。未来我们可以使用插件，从文件路由、数据库来源，甚至浏览器中获取内容。

博客的内容 content 通常以 Markdown 格式编写，所以我使用 marked 来把 Markdown 编译为 HTML，并配合 marked-highlight 与 highlight.js 提供代码高亮。

import hljs from "highlight.js";
import { Marked } from "marked";
import { markedHighlight } from "marked-highlight";

const markdownRenderer = new Marked({
  breaks: false,
  gfm: true,
});

markdownRenderer.use(
  markedHighlight({
    emptyLangClass: "hljs",
    langPrefix: "hljs language-",
    highlight(code, language) {
      const highlightLanguage = hljs.getLanguage(language)
        ? language
        : "plaintext";

      return hljs.highlight(code, { language: highlightLanguage }).value;
    },
  }),
);

await markdownRenderer.parse(markdown, { renderer });

第二步是使用模板渲染。

由于我们要编写的是网站文件，在大多数 SSG 中，这个模板一般会和 HTML 结构强相关。如果选择自定义模板语法，就需要自己定义 AST 和编译器来处理，比如 Astro 的 .astro 模板本身就是一套框架自有的组件语法。与此同时，你还需要开发用于类型检查和语法高亮的工具链，这实在不利好开发者体验。

还有一些 SSG 使用 React/Vue 组件来编写模板，这样的模板虽然开发体验不错，但它们通常会和对应框架的生态绑定得更深。如果处理不当，甚至可能默认引入客户端 JavaScript。对于 SSG 来说，默认引入任何不必要的客户端 JavaScript 都是不明智的。

所以我选择了一个轻量的方案 —— 由 Hono/JSX 驱动的 JSX 来编写模板。它可以在使用 JSX 语法的情况下进行服务端渲染，最终输出 HTML 字符串，同时保持类型安全。对于纯静态页面来说，最终输出的 HTML 文件也不需要包含任何框架相关的客户端代码。

export function HtmlArticle({ html }) {
  return (
    <div
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

const app = new Hono()
  .get("/", (c) => {
    return c.html(<HtmlArticle html={markdownRenderer.parse(markdown)} />);
  });

第三步是输出为网站文件。

定义好内容和模板之后，我们需要定义网站的结构（也可以称之为路由）。既然我们使用 Hono/JSX，那我们可以通过一个 HTTP 框架来定义路由，Hono 就是这样的。而且借助 Hono 框架，我们可以轻松启动开发服务器。

在后续，我们还可以通过这种方式进行服务端渲染（SSR），但目前我们先专注于 SSG。

Hono 提供了 toSSG 方法，能够在构建时把 Hono 应用的路由预渲染成静态文件，这样我们就可以通过 Hono 来输出静态文件了。

设置博客样式

在 JSX 中设置 CSS 一直是一个难题，比如 CSS Modules，直到诸如 TailwindCSS 这样的原子化 CSS 方案出现。

我们选择了 UnoCSS 作为我们的 CSS 解决方案，因为它可以按需生成原子化 CSS，并且提供了可编程的生成器 API，可以直接把 CSS 类名编译成 CSS 代码。

import { createGenerator, presetWind4 } from "unocss";

const uno = await createGenerator({
  presets: [presetWind4()],
});

export async function compileAtomicCss(input: string): Promise<string> {
  const { css } = await uno.generate(input);
  return css;
}

默认的博客样式我选择了一个经典的麦金塔风格，我们正在计划使用 Figma 并制作相关的 UI 组件库，以打造一个复古风格的博客主题。

后续

你也许会发现，本博客没有用到任何客户端 JavaScript，这正是我想要的，对于一个静态博客，他不需要客户端 JavaScript 的引入。

你可以在 GitHub 上找到这个项目的源代码。

我们未来应该会把这个项目变成一个真正的框架，然后推出一套自己的 UI 组件库。

以及下面的功能：

插件支持的 RSS 与 Sitemap 功能
基于 HTML Form 的搜索和评论系统
在线编译器
以及可能的 SSR 全栈支持

因为我们没有用到 Vite，也尽量避免依赖只属于 Node.js 环境的模块，所以这个框架未来甚至可以在浏览器中直接运行。