AI 脚本字母插件 topce/pizx

pizx — 带原生 Pi AI 集成的 zx fork，运行在 cordis 上

pizx — 带原生 Pi AI 集成的 zx fork

面向 Node.js 的 AI 驱动 shell 脚本 — zx 的 fork，原生集成 Pi AI，构建在 cordis 插件框架之上。核心自带 π（文本生成）、Π（编程智能体）、α（任意兼容 ACP 的智能体）、ε（任意命令行 AI harness — claude、kiro-cli、……），以及 TypeSafe 的类型化决策 choice/score/noul — 你还可以用插件定义自己的字母。每次运行都可追踪，可导出为 JSONL；可缓存的字母会命中本地结果缓存。

#!/usr/bin/env pizx

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

await Πfix the TypeScript errors in src/

快速开始

Step 1: Install Pi CLI (one-time) — needed for AI credentials
npm install -g @earendil-works/pi
pi auth login

Step 2: Install pizx in your project
npm install @topce/pizx

写一个脚本（hello.mjs）：

#!/usr/bin/env pizx

// Simple AI query
const answer = await πwhat is the capital of France?
echo(answer)

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

运行：

chmod +x hello.mjs
./hello.mjs # or: 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） |
| ε（run、harness、cli） | 任意命令行 AI harness — claude、kiro-cli、opencode、……（需要可执行文件 — 不需要 pi） |
| noul（Noul） | TypeSafe 是/否概率 — 校准过的 System One 决策 |
| choice（Choice） | TypeSafe 单选标签分类，带置信度 |
| score（Score） | TypeSafe 在有序评分表上的位置，带置信度 |

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

// α speaks the generic Agent Client Protocol — any ACP v1 server works: await α({ server: ['kiro-cli', 'acp'] })fix the TypeScript errors in src/ await α({ server: ['kiro-cli', 'acp'], session: 'review' })continue that review await α({ server: ['kiro-cli', 'acp'], permissions: 'deny' })audit without running tools

// ε runs any CLI AI harness; unknown options become its CLI flags:
await ε({ harness: 'claude', model: 'sonnet' })review this diff // claude -p --model sonnet …

// TypeSafe turns a model's judgment into a typed, calibrated value:
const refund = await noul({ instructions: 'Is a refund requested?' })${ticket}
const team = await choice({ instructions: 'Which team?', criteria: { billing: '…', tech: '…' } })${ticket} refund.text // '0.99' — the usable scalar refund.answer.confidence // full typed answer (confidence, probabilities, …)

所有字母都返回 LetterOutput：text、modelId（别名 modelUsed）、isFromCache（别名 fromCache）、计时信息，以及 token/费用 getter —— 另外还有 output.trace，记录这次调用的 LLM 调用。TypeSafe 字母和 pattern 词还会额外设置 .answer，存放结构化结果。完整选项表见：π、Π、α、ε、TypeSafe。α 和 ε 完全独立于 pi：α 驱动你指定的任意 ACP 服务器命令（支持命名会话、按需 authenticate，以及一套工具权限策略，让 pizx 始终掌管信任）；ε 驱动你已安装的任意 harness 二进制（例如 Kiro、Claude Code）。

TypeSafe 字母需要 TYPESAFE_API_KEY（获取）；客户端是懒加载的，所以从不使用它们的应用启动时不需要 key。

定义你自己的字母

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 效果），而 inject 依赖让加载顺序变得无关紧要。

Words —— 可组合的 AI 模式

Words 是组合字母构建出的具名 AI 模式；word 本身也是字母，因此 word 可以递归组合。有十一个以现成插件形式随附在 examples/plugins/ 中——其中七个模式来自 Anthropic 的 Building effective agents，另外四个是 TypeSafe 模式——它们和其他插件一样，通过 pizx.config.mjs 加载：

| Word | 别名 | 模式 |
| ralph | loop | 智能体循环——迭代式分析/规划/执行/审查 |
| fleet | parallel | 并行化：分段——拆分提示词，分发出去 |
| chain | pipeline | 提示词链——顺序步骤 + 可选门控 |
| route | branch | 路由——先分类，再分发 |
| vote | jury | 投票——N 个并行答案，汇总计票 |
| refine | optimize | 评估器-优化器——按标准反复修订，直到 PASS |
| orchestrate | director | 编排器-工作者——分解、分发、综合 |
| fanout | fan-out | TypeSafe 推测式分发——多个问题，一次调用 |
| composite | composite-scoring | TypeSafe 复合评分——加权维度 |
| gate | confidence-routing | TypeSafe 置信度门控路由 |
| intent | intent-routing | TypeSafe 意图路由——分类并分发 |

await chain({ steps: ['outline', 'π'] })write a document about X
await route({ routes: { refund: 'π', tech: 'Π' } })support query
await vote({ votes: 5 })is this diff safe to merge?
await refine({ criteria: 'no jargon, under 50 words' })explain monads
await orchestrateaudit the docs for inconsistencies

每个 word 的字母都放在可替换的槽位里——ralph({ execute: 'α' })、fleet({ worker: 'Π' })——需要选项的字母通过 word 传入选项（server、model、cwd 等会被转发）。完整参考：docs/words.md。

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

pizx --trace script.mjs # token/cache/cost summary on stderr
pizx --export-log script.mjs # .pizx/logs/<runId>.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、llm-call，其中 input/output/cache-read/cache-write token 互不重叠，还有 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()

命令行

pizx script.mjs # run a script (every registered letter is a global)
pizx -p "your prompt" # quick pi-ai query
echo "your prompt" | pizx -p - # read the prompt from stdin
pizx --acp --acp-server "kiro-cli acp" "your prompt" # quick ACP agent query
pizx --run --run-harness claude "your prompt" # quick CLI harness query
pizx --Pi "your prompt" # quick coding-agent query (Π, tools enabled)
pizx --Pi --session auth --tools read,edit "continue" # durable Π conversation
pizx --Pi --codemode "count the TS files" # + JS sandbox over tools
pizx --Pi --mcp "use the radius server" # + MCP servers from mcp.json
pizx --model <id> 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 --json -p "your prompt" # machine-readable output (implies --quiet/--no-color)
pizx --no-color script.mjs # disable ANSI color (also honors NO_COLOR)
pizx --trace --export-log s.mjs
pizx --version | --help

给智能体用的机器可读输出：--json 会输出一个结果信封
（{ text, modelId, fromCache, durationMs, tokens, costUsd }），加上
--letters 时则输出字母注册表；失败时向 stderr 打印 { error: { code, message } }，并以特定退出码退出（2 用法错误 · 3 认证错误 · 4 智能体错误 · 5 acp 错误 · 6 已取消 · 7 内部错误 · 8 harness 错误）。详见 AGENTS.md。

编程式使用

import { $, π, Π } from '@topce/pizx' // lazy default app
import '@topce/pizx/globals' // or everything as globals

import { createPizx } from '@topce/pizx' // explicit app
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()

文档

- AGENTS.md — 给编写 pizx 代码的 AI 智能体的指南（脚本模板、字母、--json、退出码）
- Onboarding — 架构与文件地图
- Defining letters — 插件 API
- Words — 把字母组合成 AI 模式（词库）
- Trace & logs — 事件格式、导出、缓存友好性
- π · Π · α · ε — 内置字母参考
- α idea — ACP 字母的设计思路与路线图

0.9 的模式去哪了？

pizx 1.0 基于 cordis 重写了核心，并内置 π、Π、α、ε —— 那 16 个硬编码的模式标签（Ralph、Fleet、Debate、Pipeline、……）已从核心部分，以字母插件的形式回归。已有七个：ralph、fleet、chain（流水线）、route（分支）、vote（评审团）、refine（优化）、orchestrate（导演），它们作为单词插件放在 examples/plugins/ 里——另外还有四个 TypeSafe 模式单词（fanout、composite、gate、intent）。参见 docs/words.md 和 docs/typesafe.md。旧代码在 0.9 分支。

许可证

MIT