oh-my-pi 共享工具库 @oh-my-pi/pi-utils 全解析:零仪式感、Bun 优先的基础设施层
oh-my-pi 共享工具库 @oh-my-pi/pi-utils 全解析:零仪式感、Bun 优先的基础设施层
导读
@oh-my-pi/pi-utils 是 oh-my-pi(⌥ 与 IDE 深度集成的编码 Agent)内部共享的 TypeScript 工具库,承载了日志、路径解析、进程生命周期、流处理、HTTP 重试等基础设施能力。本文以 packages/utils/README.md 为骨架,结合仓库源码逐模块讲解其设计意图、核心 API 与可复用价值,读完你可以直接在自己的 Bun/TypeScript 项目里以相同模式组织通用工具,也能快速定位 oh-my-pi 各包中任意一个工具函数的实现位置。
一、包定位:为 pi 系列包提供零仪式感的共享底座
@oh-my-pi/pi-utils 的定位在 README 第一句话就写得很清楚:“Shared utilities for oh-my-pi packages. Zero ceremony, Bun-first.” 它是整个 monorepo(packages/agent、packages/ai、packages/coding-agent、packages/tui 等)共用的工具箱,package.json 中声明其依赖仅有 @oh-my-pi/pi-natives(原生模块绑定),仓库元数据可参见 packages/utils/package.json。
几个值得注意的工程决策:
- 直接发布 TypeScript 源码,无构建步骤:
main与types均指向./src/index.ts(见 package.json),同时导出./<module>子路径,支持“按需导入单模块”; - Bun 优先:运行时要求
bun >= 1.3.14(engines字段),大量实现直接使用 Bun 运行时能力(Bun.which、Bun.hash、Bun.JSONL.parseChunk、Bun.sleep); - 统一入口 barrel:src/index.ts 汇总导出全部模块,其中
logger、postmortem、procmgr、prompt、ptree以命名空间形式导出,其余平铺导出,并额外提供structuredCloneJSON等组合工具。
导入方式有两种,效果等价:
// 方式一:根 barrel
import { isEnoent, $which } from "@oh-my-pi/pi-utils";
// 方式二:按模块子路径(tree-shaking 更友好)
import { getLogsDir } from "@oh-my-pi/pi-utils/dirs";
import { fetchWithRetry } from "@oh-my-pi/pi-utils/fetch-retry";
二、logger:TUI 安全的轮转文件日志中心
README 强调 logger 的核心理念:集中式日志,写入 ~/.omp/logs/,支持轮转,且绝不写 stdout——因为 oh-my-pi 是 TUI 应用,任何往 stdout/stderr 的输出都会污染终端渲染。
实现细节位于 src/logger.ts 与 src/logger/ 子目录:
- 默认输出:旋转式文件
~/.omp/logs/omp.<YYYY-MM-DD>.<PID>.log,文件名编码了日期和进程号,多个并发 omp 实例互不干扰; - 结构化 JSON 行:每条日志包含
timestamp、level、pid、message及附加 context 字段;序列化时使用专门的 replacer 展开Error对象(name/message/stack/cause 及自定义字段),避免JSON.stringify(err)输出空对象的问题; - 四种级别:
error/warn/info/debug,通过logger.error(msg, context)等命名空间函数调用; - 传输层可替换:
setTransports({ console: true, file: false })可将日志切到控制台输出,供 auth broker 等无头常驻服务对接 pm2/journald/k8s 等进程管理器;registerLogSink可注册带外日志接收器(如 OpenTelemetry),且“sinks 是旁路,绝不能破坏本地日志”; - 日志保留策略:每个进程每天保留 1 份已完成进程的日志、跨最近 5 个自然日,过期文件在初始化时由
pruneStaleProcessLogs清理,活跃 PID 命名空间不会被误删。
同一模块还内置了启动耗时分析(startTiming/endTiming/time(op, fn)),基于 AsyncLocalStorage 建立层级 span 树,支持 PI_TIMING=full|x 环境变量控制输出粒度,并可通过 PI_DEBUG_STARTUP 输出同步启动标记。这是排查“启动卡在哪个阶段”的利器。
三、dirs:配置目录解析与 XDG 迁移
dirs 模块是 omp 所有路径的唯一真相来源,实现集中在 src/dirs.ts(约 1100 行)。核心事实:
- 配置根目录:
~/.omp(CONFIG_DIR_NAME = ".omp"),可用PI_CONFIG_DIR环境变量覆盖; - 命名 Profile:支持
OMP_PROFILE(规范变量,优先)与PI_PROFILE(遗留兼容),Profile 名必须匹配/^[a-z0-9][a-z0-9._-]{0,63}$/,且不能是 Windows 保留设备名(CON/PRN/AUX/NUL/COM[0-9]/LPT[0-9]);激活后目录变为~/.omp/profiles/<name>/; - Agent 目录:默认
~/.omp/agent,可用PI_CODING_AGENT_DIR覆盖;setAgentDir/setProfile负责运行时切换并维护环境变量一致性; - XDG 兼容(Linux):设置
XDG_DATA_HOME/XDG_STATE_HOME/XDG_CACHE_HOME后,路径重定向到$XDG_*_HOME/omp/下的 data/state/cache 三类目录;重定向的前提是先执行omp config migrate(或config init-xdg)迁移数据,且“只信任环境变量、不做文件系统存在性检查”。命名 Profile 的 XDG 定位以首次激活时的 Profile 专属路径为锚,避免目录在激活间漂移。
模块导出的 getter 覆盖了全部目录约定,可直接复用:
import {
getConfigRootDir, getAgentDir, getLogsDir, getSessionsDir,
getPluginsDir, getWorktreesDir, getMemoriesDir, getAgentDbPath,
setProfile, getActiveProfile,
} from "@oh-my-pi/pi-utils/dirs";
例如 getLogsDir() 返回 ~/.omp/logs(XDG 下为 $XDG_STATE_HOME/omp/logs),getAgentDbPath() 返回 ~/.omp/agent/agent.db(settings 与 auth 存储的 SQLite 文件),getWorktreesDir() 依次取 OMP_WORKTREE_DIR 环境变量 → setWorktreesDir 覆盖(对应 worktree.base 配置)→ 默认 ~/.omp/wt。此外还提供 pathIsWithin、getSafeProjectCwd、directoryIsEnterable 等路径安全判断,以及 hashPath(Bun.hash 的 7 位 hex 摘要,用于 PR checkout 等工作树目录命名)。
四、stream:ReadableStream 之上的行/SSE/JSONL 读取
stream 模块把底层字节流抽象成三种高频消费形态(src/stream.ts):
readLines(stream, signal?):逐行产出Uint8Array,基于ConcatSink缓冲拼接跨 chunk 的半行;readSseEvents(stream, signal?):按 SSE 规范在空行边界派发事件,正确处理event:/data:(多行data:以\n拼接)/id:/retry:字段、CRLF 与注释行,并暴露raw原始行供诊断;readSseJson<T>在其上自动JSON.parse并跳过[DONE]哨兵;readJsonl<T>(stream, signal?)与parseJsonlLenient<T>:前者流式解析 JSONL,后者对完整字符串容错解析(坏行跳过到下一个换行并回调onMalformedRecord),两者均基于 Bun 原生的Bun.JSONL.parseChunk。
所有生成器都接受 AbortSignal,配合 abortable 模块的 abortableSource 实现协作式取消,中止时静默退出而非抛错。示例:
import { readSseJson } from "@oh-my-pi/pi-utils/stream";
for await (const obj of readSseJson<ChatChunk>(response.body!)) {
// 每个 SSE data: 行一个 JSON 对象
}
五、ptree / procmgr:进程树与生命周期管理
这两个模块负责 oh-my-pi 的子进程体系:
ptree:进程树模型与ChildProcess包装器,index.ts从其中额外导出ChildProcess、Exception、NonZeroExitError、AbortError,说明其抛错体系是统一的;procmgr:进程生命周期管理(spawn、监控、回收)。
它们与 postmortem 配合,保证 Agent 在退出/崩溃时能可靠地释放子进程、文件、socket 等资源。
六、postmortem:退出、信号与致命异常的清理管线
src/postmortem.ts 提供一套“注册清理回调 → 统一触发”的机制,覆盖六类退出原因:
export enum Reason {
PRE_EXIT, EXIT, SIGINT, SIGTERM, SIGHUP,
UNCAUGHT_EXCEPTION, UNHANDLED_REJECTION, MANUAL,
}
关键 API 与语义:
register(id, callback, options?):注册回调,返回永久取消函数;支持exitOnly选项——在 keep-alive 手动清理轮次中被跳过但注册保持武装,真正的退出轮次才执行(适合“进程仍持有的数据库/句柄”这类资源);cleanup():执行全部回调但不退出,随后重新武装系统,用于 worker 中“清理后继续运行”的场景;quit(code):执行清理、等待 stdout 排空(drainStdout,上限 5 秒)后经process.exit退出;主线程与 worker 行为不同(worker 只清理不退出整个进程);- 信号退出码遵循惯例:SIGINT→130、SIGTERM→143、SIGHUP→129;
- 主线程注册了完整的
SIGINT/SIGTERM/SIGHUP/uncaughtException/unhandledRejection/exit处理器,worker 线程只注册exit(避免吞掉 worker 自身的异常上报); - 清理设有 10 秒 deadline(
CLEANUP_DEADLINE_MS),超时强制退出,防止清理回调卡死进程。
模块还提供了大量“可恢复性判断”工具:isIpcSendEpipe、isInternalSocketClosedError、isWorkerIpcDeserializeError 识别 Bun 环境下可安全忽略的异步错误(worker IPC 发送竞争、node:net 内部 ERR_SOCKET_CLOSED、advanced-serialization 反序列化失败),markExpectedCleanupError/isExpectedCleanupError 标记常规资源回收产生的“预期错误”使其降级为日志,以及 registerFatalRecoveryHint 在致命错误输出前打印用户可执行的恢复命令。用法示例:
import * as postmortem from "@oh-my-pi/pi-utils/postmortem";
const cancel = postmortem.register("my-session", async (reason) => {
await cleanupMyResources(); // 退出、信号或致命异常时都会执行
});
七、fetch-retry:带服务端重试提示的 fetch 封装
src/fetch-retry.ts 提供 fetchWithRetry(url, options),是针对 LLM Provider API 场景打磨过的 HTTP 重试层,核心能力:
- 触发条件:对 5xx、408、429 以及瞬时网络错误重试,默认最多 5 次(
maxAttempts),单次延迟上限默认 60 秒(maxDelayMs); - 无提示时的退避策略:默认指数退避
500ms * 2**attempt,也可传数字、数组(按 attempt 索引、钳制到末位)或函数; - 服务端提示解析:
extractRetryHint从响应头(retry-after-ms、Retry-After、x-ratelimit-reset-ms、x-ratelimit-reset、x-ratelimit-reset-after)和响应体(OpenAI Codex / Gemini 系的 quota 文案、retryDelayJSON 字段、中文“将在 … 重置”等)提取建议延迟,超出上限的提示会让调用方立即拿到当前响应快速失败; - 可定制:
prepareInit(attempt)每次尝试叠加请求头(auth 刷新、UA 轮换),shouldRetryResponse可基于克隆的响应体快速放行确定性失败,fetch可注入代理或 mock; - Bun 超时透传:
timeout选项原样转发给底层 fetch(false可关闭 Bun 原生约 300 秒的预响应超时,流式 Provider 用它接管自己的 watchdog); - 配套导出
isRetryableStatus、isRetryableError、extractHttpStatusFromError(从错误的 status/statusCode/response.status 及消息文本中挖掘 HTTP 状态码)。
import { fetchWithRetry } from "@oh-my-pi/pi-utils/fetch-retry";
const res = await fetchWithRetry("https://api.example.com/v1/chat", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ model: "gpt-4o", messages }),
maxAttempts: 5,
maxDelayMs: 30_000,
});
if (!res.ok) handleFailure(res);
八、其他核心小工具一览
- prompt(src/prompt.ts):基于 Handlebars 的提示词模板(内部实现见 src/template.ts),支持
renderPhase(pre/post-render)、replaceAsciiSymbols、normalizeRfc2119(将 MUST/SHOULD/NEVER 等关键词加粗)等格式化选项,是 Agent 系统提示词渲染的底座; - which(src/which.ts):
$which(command, options)二进制查找,带四种缓存策略(none/fresh/ro/cached,即WhichCachePolicy.Bypass/Fresh/ReadOnly/Cached);macOS 上Bun.which失败时会回退到 Xcode/Command Line Tools 工具链目录(通过$DEVELOPER_DIR或/var/db/xcode_select_link解析活动开发者目录,用缓存目录清单代替逐命令 existsSync,不派生 xcrun 子进程); - fs-error(src/fs-error.ts):
isEnoent/isEacces/isEisdir/isEnotdir/isEexist/isEnotempty/hasFsCode等类型守卫,按错误码判断而非字符串匹配; - env / worker-host:环境变量装载与无副作用 worker-host 入口契约(
workerHostEntry),见 src/env.ts 与 src/worker-host.ts; - abortable / async:
once、untilAborted与AbortSignal感知的流/Promise 辅助(src/abortable.ts、src/async.ts); - math-delimiters:LaTeX
$...$/$$...$$定界符语法(仅偏移量),被 TUI 与 collab-web 渲染器共享(src/math-delimiters.ts); - peek-file:带缓冲池的文件前 N 字节读取(src/peek-file.ts);
- 其他单用途工具:
frontmatter(前置元数据解析)、glob、mime、temp、format、color、snowflake(分布式 ID)、tab-spacing、path-tree、sanitize-text,以及structuredCloneJSON(src/index.ts 中的深度克隆助手,优先structuredClone、失败回退 JSON round-trip)。
九、安装与本地体验
包发布在 npm 上,作为普通依赖安装即可(项目本身使用 Bun 作为包管理器):
bun add @oh-my-pi/pi-utils
由于包直接分发 TypeScript 源码,无需构建即可获得完整类型。本地验证与开发围绕仓库中的 packages/utils/package.json 脚本展开:
bun install # 安装依赖(monorepo 内亦可从根目录统一安装)
bun test # 并行运行测试(bun test --parallel)
bun run check # lint + 格式检查 + 类型检查(oxlint / oxfmt / tsgo)
bun run lint # 仅 oxlint
bun run fmt # oxfmt 自动格式化
若想在本仓库内追踪某个工具的演进,可对照 packages/utils/CHANGELOG.md 查看版本变更记录。
十、小结:一份可迁移的 Bun 工具库设计范式
@oh-my-pi/pi-utils 的价值不在于某个单一“大招”,而在于一整套克制而自洽的工程决策:TUI 安全的日志落盘、单一路径权威源、规范化的进程清理管线、对 Provider 异质错误文案的宽容解析,以及“源码直发、Bun 优先、按需子路径导入”的发布策略。无论是想深入 oh-my-pi 的 Agent 实现,还是在自己的 Bun/TypeScript 项目里建立同类基础设施,这份工具库都是值得对照学习的参考实现。