内容
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./docs/banner.svg">
<source media="(prefers-color-scheme: light)" srcset="./docs/banner.svg">
<img src="./docs/banner.svg" alt="HITL 工具包 — 人机协作 AI，精准测量" width="100%">
</picture>
# HITL 工具包
> 面向智能用户界面的人机协作 AI 原语。
HITL 工具包是 [**akaOSS**](https://www.akaoss.dev) 的一部分 — 网站、文档、[论文](https://www.akaoss.dev/paper) 和 [组件注册中心](https://www.akaoss.dev/registry) 都托管在 [akaoss.dev](https://www.akaoss.dev) 上。**该仓库是 `@hitl-kit/*` 库的 monorepo**：六个 npm 包、LangGraph 演示应用和设计文档。
[**项目页面**](https://www.akaoss.dev/projects/hitl-kit) · [**组件画廊**](https://www.akaoss.dev/components) · [**注册中心**](https://www.akaoss.dev/registry) · [**论文**](https://www.akaoss.dev/paper)
---
## 为什么存在
95% 的企业 AI 试点项目都失败了 — 不是因为模型不好，而是因为我们衡量的是错误的东西。当前的基准测试询问的是 *"模型是否可以自主完成这个任务？"* 而部署时询问的是 *"它是否尊重用户的权威，保护用户的代理权，并随着时间的推移让用户变得更好？"* 这两个问题之间的差距是试点项目失败的地方 — 而这个工具包中的每个原语都存在于这个差距中。
设计学科：十五个 UI 原语中的每一个都是来自 [AI 测量问题](https://www.akaoss.dev/paper) 的特定声明的物理体现。MiniTrace 实例化了 HotpotQA 的支持事实要求；AI 生成规模将 Dhillon 等人的脚手架发现操作化；中断卡是保护代理的边界。如果一个原语不能与论文中的声明联系起来，那么它就不会被发布。下面这些包将该协议带入到实际的代理栈中。完整的深入了解：[akaoss.dev/projects/hitl-kit](https://www.akaoss.dev/projects/hitl-kit)。
## 包
| 包 | 版本 | 描述 |
|---|---|---|
| [`@hitl-kit/core`](https://www.npmjs.com/package/@hitl-kit/core) | 0.5.0 | 人机协作 AI 原语的 Zod 事件模式。每个 HITL 工具包适配器共享的框架无关协议。 |
| [`@hitl-kit/react`](https://www.npmjs.com/package/@hitl-kit/react) | 0.4.2 | `HitlEventRenderer`，一个类型化的调度器，将验证的 HITL 事件映射到 React 原语。与 `@hitl-kit/core` 和任何 shadcn 安装的 HITL 原语配对。 |
| [`@hitl-kit/gates`](https://www.npmjs.com/package/@hitl-kit/gates) | 0.2.0 | 可组合的决策门（置信度、成本、范围、审批链、速率限制）。纯函数，包装任何适配器的发射点，决定允许 / 拒绝 / 升级。 |
| [`@hitl-kit/langgraph`](https://www.npmjs.com/package/@hitl-kit/langgraph) | 0.6.1 | LangGraph 适配器。从 LangGraph `interrupt()` 节点发出符合模式的 HITL 事件，并使用类型化的 `Command` 有效负载恢复。 |
| [`@hitl-kit/ai-sdk`](https://www.npmjs.com/package/@hitl-kit/ai-sdk) | 0.7.1 | Vercel AI SDK 适配器。类型化的 `tool()` 包装器，返回符合模式的 HITL 事件，以便 `<HitlEventRenderer />` 可以在客户端调度它们。 |
| [`@hitl-kit/mcp`](https://www.npmjs.com/package/@hitl-kit/mcp) | 0.8.0 | MCP 服务器，暴露 15 种 HITL 原始事件类型为 MCP 工具，以便 Claude Code、Cursor、Claude Desktop 和任何 MCP 感知客户端都可以发出验证的、人机协作的事件。 |
---
## 安装
库包可以从 npm 安装：
```bash
pnpm add @hitl-kit/core @hitl-kit/react
```
UI 原语通过 shadcn CLI 从 HITL 工具包注册中心安装（由 akaOSS 站点提供 — 这些 URL 保持有效）：
```bash
npx shadcn@latest add https://www.hitlkit.dev/r/hitl-card.json
```
CLI 自动解析注册中心依赖项（`hitl-utils`、`hitl-types`）和 npm 依赖项（`lucide-react`）。在 [akaoss.dev/registry](https://www.akaoss.dev/registry) 上浏览每个原语，并使用复制粘贴安装命令在 [akaoss.dev/components](https://www.akaoss.dev/components) 上查看它们。
---
## 使用事件渲染器
对于智能用户界面，将组件与 `@hitl-kit/core`（Zod 事件模式）和 `@hitl-kit/react`（`HitlEventRenderer`）配对：
```tsx
import { createRegistry, HitlEventRenderer } from "@hitl-kit/react";
import { HitlCard } from "@/components/hitl/HitlCard";
const registry = createRegistry({
"hitl.card": (event) => (
<HitlCard
config={{
id: event.id ?? "default",
kind: event.variant,
title: event.title,
subtitle: event.subtitle,
steps: event.steps,
runLabel: event.runLabel,
editPlaceholder: event.editPlaceholder,
openTab: "human",
}}
/>
),
});
// 稍后，当您的代理发出验证的 HITL 事件时：
<HitlEventRenderer event={event} registry={registry} />;
```
渲染器在运行时通过共享的 Zod 模式验证事件，根据 `event.kind` 进行缩小，并安装为该类型注册的原语。无论哪个代理框架生成事件，其工作方式都相同。
---
## 与 LangGraph 一起使用
`@hitl-kit/langgraph` 将 LangGraph 的原生 `interrupt()` / `Command({ resume })` 原语转换为类型化的 HITL 事件生产者。图形暂停，UI 通过 `<HitlEventRenderer />` 渲染原语，人类操作，图形恢复。端到端，无需胶水。
```bash
pnpm add @hitl-kit/core @hitl-kit/react @hitl-kit/langgraph @langchain/langgraph
```
```ts check
import { StateGraph, interrupt } from "@langchain/langgraph";
import { createHitlCardInterrupt } from "@hitl-kit/langgraph";
// 在节点内...
const approval = interrupt(
createHitlCardInterrupt({
variant: "review",
title: "需要验证引文",
subtitle: "IPCC 2023 · p. 12",
steps: [
{ label: "由代理标记", done: true },
{ label: "确认", done: false },
],
runLabel: "确认并继续",
}),
);
// 图形暂停；`Command({ resume: { approved: true } })` 导致此行返回 `{ approved: true }`
```
在客户端，使用 `isHitlInterrupt` 进行保护，并通过相同的 `<HitlEventRenderer />` 渲染。每个原语都有一个匹配的 `create<Name>Interrupt` 帮助函数，在发出时根据核心 Zod 模式进行验证，因此在客户端出现格式错误的事件会抛出异常。
---
## 与 Vercel AI SDK 一起使用
`@hitl-kit/ai-sdk` 提供了 15 个类型化的 `tool()` 包装器 — 每个 HITL 工具包原语一个 — 返回验证的 HITL 事件作为工具结果。由于 AI SDK 没有原生的中断原语，适配器返回“等待人类”为工具调用结果；消费者渲染事件并附加后续用户消息以继续对话。
```bash
pnpm add @hitl-kit/core @hitl-kit/react @hitl-kit/ai-sdk ai zod
```
```ts
import { generateText } from "ai";
import { hitlCardTool, approveRejectTool, allHitlTools } from "@hitl-kit/ai-sdk";
const result = await generateText({
model,
messages,
tools: {
requestHumanReview: hitlCardTool({
description: "在编写之前请求人类审查引文。",
}),
requestApproval: approveRejectTool(),
},
});
// 如果模型调用 requestHumanReview，则工具结果是验证的 HitlCardEvent。
// 或一次性传递所有 15 个：tools: allHitlTools
```
在客户端，使用 `isHitlToolResult` 筛选 HITL 工具结果，并通过 `<HitlEventRenderer />` 渲染每个结果。
---
## 添加门
门是一种纯粹的决策函数：置信度太低？成本超出预算？范围超出允许范围？拒绝 — 并（默认）显示一个 HITL 升级卡，让人类可以覆盖。相同的渲染器管道处理允许和阻止路径。
```bash
pnpm add @hitl-kit/gates
```
```ts check
import {
composeGates,
confidenceGate,
costGate,
scopeGate,
rateLimitGate,
inMemoryStore,
} from "@hitl-kit/gates";
const store = inMemoryStore();
const gates = [
confidenceGate({ min: 0.85 }),
costGate({ maxUsd: 0.10 }),
scopeGate({ allowed: ["read:files", "read:web"] }),
rateLimitGate({ store, key: (ctx) => ctx.signals?.userId ?? "anon", max: 30, windowSec: 60 }),
];
```
通过适配器助手将它们连接起来：
```ts
// LangGraph
import { withGates } from "@hitl-kit/langgraph";
const gated = await withGates(payload, gates, { signals });
const approval = interrupt(gated);
// Vercel AI SDK
import { withGates } from "@hitl-kit/ai-sdk";
const tool = withGates(hitlCardTool(), gates, { signals: (input) => deriveSignals(input) });
// MCP — 在服务器创建时配置门
import { createHitlKitServer } from "@hitl-kit/mcp";
const server = createHitlKitServer({ gates, onDeny: "escalate" });
```
当门拒绝时，默认的 `onDeny` 结果是门的升级 `HitlEvent` — 将其输入到您已经使用的 `<HitlEventRenderer />` 中。在 [packages/gates/README.md](./packages/gates/README.md) 中有完整的详细信息。
---
## 与 MCP · Claude Code, Cursor, Claude Desktop 一起使用
`@hitl-kit/mcp` 是一个 MCP 服务器，暴露了所有 15 种原始事件类型为 MCP 工具。将它放入任何 MCP 感知客户端，每个客户端的代理都可以发出验证的、人机协作的事件。无需每个客户端适配器代码。
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"hitl-kit": {
"command": "npx",
"args": ["-y", "@hitl-kit/mcp"]
}
}
}
```
### Claude Code
```bash
claude mcp add hitl-kit npx -y @hitl-kit/mcp
```
### Cursor
光标设置 → MCP 服务器 → 添加，JSON 与 Claude Desktop 相同。
注册并重启客户端后，`hitl_interrupt_card`、`hitl_qa_flow` 和另外 13 个工具可用。每个工具都根据核心 Zod 模式验证输入并返回一个 JSON `HitlEvent`，准备好供您的 UI 使用。
---
## 演示应用
[`apps/demo-langgraph`](./apps/demo-langgraph) 是一个最小的 Next.js 应用，它端到端地运行整个流程：带有真实 `interrupt()` 节点的 LangGraph，通过 `<HitlEventRenderer />` 渲染的中断卡，审批和 `Command({ resume })`。它还具有 AI SDK 流（`/ai-sdk`）、门（`/gates`）和 v0.6a 原语（`/diff`、`/citation`、`/plan`、`/tool-calls`）的选项卡。
```bash
pnpm install
pnpm --filter demo-langgraph dev # http://localhost:3100
```
---
## 此仓库中有什么
```
.
├── packages/
│ ├── core/ @hitl-kit/core（Zod 事件模式）
│ ├── react/ @hitl-kit/react（HitlEventRenderer）
│ ├── gates/ @hitl-kit/gates（5 个可组合的决策门）
│ ├── langgraph/ @hitl-kit/langgraph（中断帮助函数 + withGates）
│ ├── ai-sdk/ @hitl-kit/ai-sdk（Vercel AI SDK 工具包装器 + withGates）
│ └── mcp/ @hitl-kit/mcp（MCP stdio 服务器，带有门钩，hitl-kit-mcp 二进制文件）
├── apps/
│ └── demo-langgraph/ LangGraph 中断/恢复端到端演示（端口 3100）
├── docs/
│ ├── api-unification.md v0.7 API 统一设计文档
│ └── EVAL_KIT_BRIEF.md 历史设计简介
├── .github/workflows/ci.yml 构建 → 类型检查 → 测试 → 审计
└── CONTRIBUTING.md 验证和分支协议
```
工作室网站、论文源和 shadcn 注册中心源已移至 [akaieuan/akaOSS](https://github.com/akaieuan/akaOSS)，并托管在 [akaoss.dev](https://www.akaoss.dev) 和 [hitlkit.dev](https://www.hitlkit.dev) 上。注册中心安装 URL（`hitlkit.dev/r/*.json`）不受影响。
---
## 开发
```bash
pnpm install
pnpm packages:build # 通过 tsup 构建所有 @hitl-kit/* 包
pnpm packages:typecheck # 每个包中的 tsc --noEmit
pnpm test # 整个 packages/*/src 的 vitest
pnpm verify # 全部三个，按顺序运行 — 在推送之前运行
```
### 测试
Vitest 仅针对 `packages/*/src` 运行。目前 **13 个文件中的 63 个测试**：每个事件类型的往返解析 + 完整性 + 冻结的固定数据在 `@hitl-kit/core` 中，每个门的工厂，组合，存储，速率限制和审批链在 `@hitl-kit/gates` 中，以及每个适配器的集成测试（`withGates` 允许 + 升级 + 抛出）。
```bash
pnpm test # 单次运行
pnpm test:watch # 监视模式
```
---
## 贡献
问题和 PR 欢迎。对于实质性更改，请先打开一个问题，以便我们达成一致。验证和分支协议在 [CONTRIBUTING.md](./CONTRIBUTING.md) 中记录 — 每次推送前运行 `pnpm verify`；CI 运行构建 → 类型检查 → 测试以及依赖项审计，如果出现高或关键警告，则失败。
良好的首次贡献：
- 无障碍改进（ARIA，键盘导航）— v0.7 无障碍通过在 [docs/api-unification.md](./docs/api-unification.md) 中规划
- `packages/core` 中更好的 Zod 模式类型
- 文档修复
组件/注册中心贡献（15 个 UI 原语）现属于 [akaieuan/akaOSS](https://github.com/akaieuan/akaOSS)。
---
## 许可证
[MIT](./LICENSE)。随便你怎么用。
---
## 致谢
由 [Ieuan King](https://aka4uh.com) ([@akaieuan](https://x.com/akaieuan)) 构建。
该组件集最初是从 [Agatha](https://aka4uh.com) 中提取的，这是一个研究代理工作区，并被概括为一个开放的原语库。项目背后的观点论文 — [AI 测量问题](https://www.akaoss.dev/paper) — 提出了 Assist-Not-Complete 范式：根据 AI 是否协助人类而不是取代人类来评估 AI，而不是根据 AI 是否能独立完成任务。
