# @adeildo/pi-kit 中文文档

规范地址：https://npmcn.com/package/%40adeildo/pi-kit/

版本：6\.0\.0
npm 元数据更新时间：2026-11-02T14:01:05.360Z
中文译文更新时间：2026-11-06T08:28:44.988Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adeildo/pi-kit
原文对照：https://npmcn.com/package/%40adeildo/pi-kit/?lang=original
项目主页：https://github.com/felipeadeildo/pi-harness#readme
源码仓库：https://github.com/felipeadeildo/pi-harness

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：283 kB，80 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-09-30T13:33:47.160Z
- 最新版本发布：2026-11-02T14:01:04.976Z
- 近 30 天下载量：3847（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

Pi-harness 套接字的应用程序构建器,设置和事件都建立在上.

## 安装

```sh
npm install @adeildo/pi-kit
```

也可以使用：`pnpm add @adeildo/pi-kit`、`yarn add @adeildo/pi-kit`、`bun add @adeildo/pi-kit`

## README

# 翻译:

[![npm](https://img.shields.io/npm/v/@adeildo/pi-kit)](https://www.npmjs.com/package/@adeildo/pi-kit)

**图书馆在每一块 [鸡尾酒](https://github.com/felipeadeildo/pi-harness)。 。 。 .**  
应用程序构建器、功能范围、多个扩展共享的设置和设置屏幕 `Alt+S`屏幕是它给Pi添加的.

`npm install @adeildo/pi-kit`

这是一个图书馆,而不是一个皮包。 它的API跟随包裹的需求,对其他人没有承诺.

## 应用程序和其中的特征

```ts
import { createApp, defineFeature, matching, setting } from "@adeildo/pi-kit";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export const version = setting({
    id: "subscription.claudeCodeVersion",
    default: "2.1.280",
    decoder: matching(/^\d+\.\d+\.\d+$/, "a version like 2.1.280"),
});

export const subscription = defineFeature({
    id: "subscription",
    description: "Bill Anthropic OAuth requests to the Claude plan",
    settings: [version],
    setup(scope) {
        scope.on("before_provider_headers", (event) => {
            event.headers["user-agent"] = `claude-cli/${version.get(scope)}`;
        });
    },
});

export default function (pi: ExtensionAPI): void {
    createApp(pi, { name: "pi-harness" }).use(subscription).build();
}
```

每个软件包声明的扩展是一个具有一个或多个特性的应用程序. 应用程序 `name` 在每一个警告之前。 吊带宣布每个功能一个延伸,所以 `pi config` 自动关闭, 他们都读取相同的设置文件 .

## 有个什么特点

`setup` 获得该特性的范围。 它延伸 `ExtensionAPI`,所以每一种pi方法都在那里, 这些线到特征:

| 范围 | 对 |
| --- | --- |
| `scope.on` | `pi.on`,有错误 `pi-harness: permission: tool_call: boom`。它仍然掷出,因为 `tool_call` 丢出处理器是 pi 如何阻塞工具 |
| `scope.registerCommand` | `pi.registerCommand`。如果同一应用程序中的另一个功能取了这个名称,则此功能将带有警告被跳过 |
| `scope.onSessionStart` | 一旦会话设置被装入就运行 。 任何能持续的东西,如监视器或儿童过程,都从这里开始,从不进入 `setup` |
| `scope.onShutdown` | 每会话运行一次,最先更新,即使Pi起火 `session_shutdown` 两次 |
| `scope.screen` | 非设置的设置屏幕上的行 |
| `scope.warn` | 在有UI时显示通知, 在没有时写给 stderr 。 在会话开始前发送的信件等待它 |
| 其他的都一样 | 范围是扩展 API,所以 `scope.registerTool`, (中文(简体) ), `scope.appendEntry`, (中文(简体) ), `scope.events` 和其余的工作 他们总是做 |

A 类 `setup` 投出一个警告 其它的特征仍然在上升 如果一个 Pi 进程中的两个应用程序挂载相同的特性 id, 第一个运行它, 第二个日志谁拥有它 .

## 还有什么可以分享的

除了应用程序和设置之外,套件还持有每套件会写出两次的东西.

| 模块 | 它给的是什么 |
| --- | --- |
| `ui/frame.ts`, (中文(简体) ), `ui/entry.ts`, (中文(简体) ), `ui/glyphs.ts`, (中文(简体) ), `ui/scroll.ts` | 框框 条子穿, 线条和格言 它被绘制 |
| `format.ts` | 代币计数,价格和一天的时间读取 脚印、面板和桌子都一样 |
| `betas.ts` | 将β合并成Anthropic请求载体,当不需要添加时,有效载荷保持不变 |
| `events/log.ts` | 文件夹日志每个会话附加并读取 |
| `sources/` | 要显示的会话, 从此 pi 或从它的文件读取, 随其增长而随之 |
| `app/renderers.ts` | 工具和消息渲染器将特性寄存器解析, 当 pi 解析时解决, 因此视图绘制另一个会话的条目的方式相同 |
| `contracts/`, (中文(简体) ), `board/` | 此套件的名称会写入一个 pi 会话和交叉套件的事件, 以及棋盘本身的类型 |

## 设置

每个应用程序都读 `~/.pi/agent/extensions/pi-harness/settings.json`设置 `id` 它的路径在那个文件中。 一个商店只读取它自己宣布的特性的设置,所以属于另一个应用程序的密钥从不产生警告.

`store.set` 写入一个值和 `store.setAll` 在一个传中数个,这就是一个特性在保存一个完整的配置对象时所做的. 已经读取了相同内容的值没有被写入,所以文件持有的是被决定的,而不是每个默认的复制件,这样就会被冻结.

一个设置 `project: true` 也读作 `<project>/.pi/extensions/pi-harness/settings.json`,但只有一次Pi信任项目,项目价值在那里获胜. 没有这道旗的任何东西都是全球性的,试图设置它的项目文件都会得到警告,所以一个被克隆的寄存器不能不询问就放松运行.

无法解码的值会被忽略,警告名称为文件和密钥 .

## 设置屏幕

`Alt+S` 或者说 `/harness` 打开它。 每个功能都是分页,行从两个位置来.

带有 `ui` 获得一行 :

```ts
export const cursor = setting({
    id: "look.frame.cursor",
    default: "bar",
    decoder: literal("block", "bar", "underline"),
    ui: { section: "Editor", label: "Cursor", description: "The editor's cursor." },
});
```

解码器取出编辑器: `boolean` 是一个切换, `literal` 一个选择, `integer` 一个数字, `stringList` 名单. `ui.control` 标签选项或添加预设.

还有什么要说的 `scope.screen`数字 : `value` 为会话状态, `action` 为了跑步, `info` 说实话.

```ts
scope.screen.action({
    id: "judge.test",
    section: "Judge",
    label: "Test the judge",
    description: "Sends one real request.",
    run: (ctx) => probe(ctx),
});
```

屏幕上输入的值通过与文件相同的解码器. 特性选项 `tab` 财务报告和审定财务报表 `sections` 设置标签名称和分区顺序.

## 关闭一个特性

每个功能也得到 `features.<id>.enabled`,默认情况下。 一个从未运行的功能 `setup`,所以它记录什么也没有损失。 变化在接下来 `/reload`。 。 。 .

## 事件和合同

```ts
// contracts/accounts.ts
export const ACCOUNT = defineContract<AccountState, string>("accounts:state", decoder);

ACCOUNT.provide(scope, (provider) => inUse(provider)); // the owner answers
ACCOUNT.current(scope, "anthropic"); // a reader asks while drawing
ACCOUNT.changed(scope, state, "anthropic"); // the owner announces a change
ACCOUNT.onChanged(scope, (state, provider) => …); // a bridge follows it
```

合同是一个特征所知道的,另一个特征所读的。 它走过来了 `pi.events`,询问 `harness:<name>` 并公布于 `harness:<name>:changed` 有了全新的价值,所以桥梁可以跟随每份合同而无需投票. 带有密钥的合同,如呼叫的裁决或提供者的账户,将密钥作为又一个论据. 无论是共享一个应用还是来自不同的软件包,有两个特性的行为都是一样的. 该值可能出自另一个包的更古老或更新版本,因此在到达时会被解码,而一个不解码的则会被以警告的方式丢出.

这些规则适用于每一项合同:

-   它被宣布为 `contracts/` 在这里,从来没有在包 拥有国家。 读者则不依赖主人,两者均不相干.
-   值是普通的JSON,没有函数、类或 `Date`,所以远程控制或网络UI可以转发任何合同而不知道里面有什么.
-   价值可以获得田地,但永不丧失.

要显示的会话是例外: a `SessionSource` 是一个具有函数的对象, 因此它在原始通道上运行 `harness:sources`远程回答. `sourceFor` 当会话在此机器上时, 将返回到会话文件 。 屏幕上显示一个就完了 `contracts/views.ts`数字 : `openView` 询问 `harness:view.open`,以及 `canOpenView` 有谁愿意.

## 测试

`@adeildo/pi-kit/testing` 已经 `fakePi()`, (中文(简体) ), `fakeScope()` 财务报告和审定财务报表 `fakeContext()`。两个假的一 `createEventBus()` 在同一 Pi 进程中表现为两个扩展,以及 `fire` 运行处理器的顺序 并返回每个返回的东西.

[![adeildo.dev](https://adeildo.dev/assets/images/cat.svg)](https://adeildo.dev/)  
[鸡尾酒](https://github.com/felipeadeildo/pi-harness) 由 [adeildo.dev (英语)](https://adeildo.dev/)

## 常见问题

### @adeildo/pi-kit 是什么？

Pi-harness 套接字的应用程序构建器,设置和事件都建立在上\.

### 如何安装 @adeildo/pi-kit？

在项目目录运行 npm install @adeildo/pi-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-ai（\*）、@earendil-works/pi-tui（\*）、@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @adeildo/pi-kit 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adeildo\_\_pi-kit 是否存在。

### @adeildo/pi-kit 支持 ESM 还是 CommonJS？

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

### @adeildo/pi-kit 可以商用吗？

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

### @adeildo/pi-kit 的下载量有多少？

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

### @adeildo/pi-kit 还在维护吗？

最新版本 6\.0\.0 发布于 2026/11/02（5 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/09/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。