@haikit/core

中文文档
0.35.2发布于 2026/11/07MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 4837

The haikit contract layer: declare a UI surface once, implement it on the server and in the browser. Isomorphic, zero runtime dependencies.

原始使用文档

@haikit/core

The contract layer. Isomorphic, zero runtime dependencies — imported by the server runtime, the browser client, every adapter, and both halves of your app.

import { defineSurface, resolve, query } from "@haikit/core";

export const picker = defineSurface({
  name: "flight_table",
  version: 1,
  props: z.object({ flights: z.array(Flight) }),
  actions: { select: resolve(z.string()) },
  queries: { filter: query(FilterArgs) },
});

Schemas are accepted structurally — anything with a .parse() method works, so zod is your choice rather than this package's dependency.

The four guarantees

Enforced in the type system, and asserted by test/types/guarantees.ts:

a surface cannot exist without a digest, nor a notice without its model textboth are required fields
a query's result can only be produced by cap()Capped has no other constructor
mode: "elicit" needs a resolve actionotherwise the call does not typecheck
an undeclared action does not existthe contract is the allowlist

A surface can also declare staleAfterMs, how long its data may be acted on: milliseconds, or "never", which is the default. Once any surface in a conversation is past its window, the conversation closes.

A notice, declared with defineNotice, is something the server tells a conversation outside of any request. Its payload goes to the browser and its model text to the model, in the next user message; model returns null when the model needn't hear it. hai.notify types the payload from the contract. A notice declared with kind: "wake" also starts a turn, so its model must return text: null is a compile error.

A signal, declared with defineSignal, is a broadcast to every open browser, such as how many people are online. It belongs to no conversation and never reaches the model, so it has no server half: hai.signal types the payload from the contract alone.

npm run typetest at the repo root compiles those tests twice — once with their @ts-expect-error directives (must be clean) and once stripped (every marked line must error). A guarantee that silently stops working fails CI.

版本与发布记录

@haikit/core 共发布 48 个版本,首次发布于 2026/09/23;过去 12 个月发布了 48 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.35.2latest2026/11/0710 天前
0.35.12026/11/0611 天前
0.35.02026/11/0611 天前
0.34.02026/11/0512 天前
0.33.02026/11/0512 天前
0.32.02026/11/0314 天前

关于 @haikit/core 的常见问题

@haikit/core 是什么?

The haikit contract layer: declare a UI surface once, implement it on the server and in the browser. Isomorphic, zero runtime dependencies.

如何安装 @haikit/core?

在项目目录运行 npm install @haikit/core,或使用 pnpm add / yarn add / bun add。

@haikit/core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@haikit/core 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@haikit/core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@haikit/core 可以商用吗?

@haikit/core 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@haikit/core 的下载量有多少?

根据 npm 官方下载统计,@haikit/core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,837 次,日均约 161 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@haikit/core 还在维护吗?

最新版本 0.35.2 发布于 2026/11/07(10 天前);至今共发布 48 个版本,其中过去 12 个月发布了 48 个;首次发布于 2026/09/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。