AI 脚本字母插件topce/pizx

pizx — 基于 cordis 的原生 Pi AI 集成 zx 分支

npm version
GitHub Sponsors

pizx — 原生 Pi AI 集成 zx 分支

面向 Node.js 的 AI 驱动 shell 脚本 — 一个 zx 分支，集成了原生 Pi AI，构建于 cordis 插件框架之上。核心内置三个字母 — π（文本生成）、Π（编码代理）和 α（任何兼容 ACP 的代理）— 你也可以将自定义字母定义为插件。每次运行都可追踪，并可导出为 JSONL，可缓存的字母会命中本地结果缓存。

#!/usr/bin/env pizx

const answer = await πwhat is the capital of France?
echo(answer)

await Πfix the TypeScript errors in src/

快速开始

第 1 步：安装 Pi CLI（一次性）— AI 凭证所需
npm install -g @earendil-works/pi
pi auth login

第 2 步：在你的项目中安装 pizx
npm install @topce/pizx

编写脚本（hello.mjs）：

#!/usr/bin/env pizx

// 简单的 AI 查询
const answer = await πwhat is the capital of France?
echo(answer)

// Shell + AI，zx 风格
const files = await $ls src/
const summary = await πsummarize these files in one sentence: ${files}
console.log(summary)

运行它：

chmod +x hello.mjs
./hello.mjs          # 或：pizx hello.mjs

前置要求： Node.js >= 22.19.0，Pi AI CLI 已通过 pi auth login 配置。
无需单独安装 zx — pizx 已捆绑 zx；$、cd、echo、fetch 等均已内置。

字母

| 字母 | 功能 |
|---|---|
| π (pi, ai) | Pi AI 文本生成 — 向模型提问任何内容，流式输出，缓存结果 |
| Π (Pi, piAgent, codingAgent) | 带工具的 Pi 编码代理（read、bash、edit、write、grep 等） |
| α (acp, agent) | 任何兼容 ACP 的编码代理（需要服务器 — 无需 pi） |

const answer = await π({ model: 'anthropic/claude-sonnet-4-5' })explain async/await
const json = await π.quiet()generate a JSON array of 5 colors
for await (const chunk of π.streamtell me a story) process.stdout.write(chunk)

await Π({ tools: ['read', 'bash', 'edit'] })refactor the auth module

// α 使用通用的 Agent Client Protocol — 任何 ACP v1 服务器均可：
await α({ server: ['kiro-cli', 'acp'] })fix the TypeScript errors in src/

三者都返回一个 LetterOutput：text、modelUsed、fromCache、计时信息，
以及 token/成本 getter — 外加 output.trace，包含该次调用的 LLM 调用记录。
完整选项表：π、Π、
α。α 完全独立于 pi：安装你想要的代理 CLI（例如
Kiro）并传入其命令即可。
定义你自己的字母

pizx 是一个插件宿主。一个字母就是一个 cordis 插件，它注册一个模板标签——完整指南见 docs/extension.md：

// plugins/summarize.mjs
import Schema from 'schemastery'

export const name = 'summarize'
export const inject = ['letters', 'llm']

export function apply(ctx) {
ctx.letters.define('Σ', {
aliases: ['summarize'],
options: Schema.object({ maxWords: Schema.natural().default(30), model: Schema.string() }),
run: async (prompt, opts, { ctx }) => {
const result = await ctx.llm.ask(
Summarize in at most ${opts.maxWords} words:\n\n${prompt},
{ model: opts.model }
)
return result.text
},
})
}

export default { name, inject, apply }

// pizx.config.mjs — next to your script (loaded automatically)
import summarize from './plugins/summarize.mjs'
export const plugins = [summarize]

#!/usr/bin/env pizx
const summary = await Σ({ maxWords: 20 })pizx is…

你的字母会自动获得完整的内置开发体验：选项链式调用、.quiet / .cache 变体、.stream 支持、追踪、缓存以及全局注入（pizx --letters 会列出它们）。冲突会报错，卸载插件会移除其字母（cordis effects），而 inject 依赖让加载顺序变得无关紧要。

可追踪、可导出、缓存友好

pizx --trace script.mjs                 # token/cache/cost summary on stderr
pizx --export-log script.mjs            # .pizx/logs/.jsonl
pizx --export-log /tmp/run.jsonl s.mjs  # explicit path (also on crashes)
pizx --cache script.mjs                 # enable the local result cache

每次运行都是一个可导出为 JSONL 的事件日志（run-start、letter-start、带有互不重叠的 input/output/cache-read/cache-write token 的 llm-call、cache-hit/cache-miss、letter-end、run-end）——deepseek-harness 风格。--trace 会打印总计；对可缓存字母的重复调用会命中内容寻址的本地缓存（.pizx/cache，TTL + LRU），并记录 cache-hit 而不是发起 LLM 调用。Π 会话按模型/工具进行池化，从而保持提供商提示缓存处于热状态。详情见：docs/trace.md。

const app = await createPizx({ cache: true })
const first = await app.π.cachewhat is 7! + 5?
const second = await app.π.cachewhat is 7! + 5?
second.fromCache            // true — no second LLM call
app.exportLog('jsonl')      // the whole run, one event per line
await app.dispose()

CLI

pizx script.mjs                # run a script ($, π, Π, α and your letters as globals)
pizx -p "your prompt"          # quick pi-ai query
pizx --acp --acp-server "kiro-cli acp" "your prompt"  # quick ACP agent query
pizx --model  script.mjs   # model for the run
pizx --config ./cfg.mjs s.mjs  # load plugins from a config file
pizx --letters                 # list registered letters
pizx --cache | --no-cache      # toggle the local result cache
pizx --trace --export-log s.mjs
pizx --version | --help
编程式使用
js
import { $, π, Π } from '@topce/pizx'          // 懒加载默认应用
import '@topce/pizx/globals'                   // 或将所有内容作为全局变量

import { createPizx } from '@topce/pizx'       // 显式应用
const app = await createPizx({ cache: true, plugins: [summarize] })
await app.πhello
await app.letter('Σ')summarize this
console.log(app.traceSummary())
await app.flushLog('run.jsonl')
await app.dispose()

文档

- 入门指南 — 架构与文件映射
- 定义字母 — 插件 API
- 追踪与日志 — 事件格式、导出、缓存友好性
- π · Π · α — 内置字母参考
- α 构想 — ACP 字母的设计理念与路线图

0.9 版本的模式去哪了？

pizx 1.0 在 cordis 上重写了核心，并提供了 π、Π 和 α —— 16 个
硬编码的模式标签（Ralph、Fleet、Debate、Pipeline 等）已从核心中移除，
它们可以作为字母插件回归（移植示例见 examples/plugins/ralph.mjs）。
旧代码保留在 0.9 分支中。

许可证

MIT