oh-my-pi 共享工具库 @oh-my-pi/pi-utils 全解析:零仪式感、Bun 优先的基础设施层

原创2026-09-12 23:31:131,648 阅读
文章标签:代码智能体AI Agent人工智能大模型CLI开发工具工具调用

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 文案、retryDelay JSON 字段、中文“将在 … 重置”等)提取建议延迟,超出上限的提示会让调用方立即拿到当前响应快速失败;
  • 可定制: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 项目里建立同类基础设施,这份工具库都是值得对照学习的参考实现。

登录后查看全文
oh-my-pi