pi-kit

自用的 Pi 增强套件，统一安装个人使用的 Pi 扩展功能。当前支持 Pi 1.1.0。

包含目的优先的紧凑工具 UI、原生 codemode 子调用展示、完整 Open TUI 外观与统一交互设置、可选 FFF 执行集成、终端标题状态、图片生成工具，以及可选的 liuovo-claude 主题。

仓库：liuc-c/pi-kit · npm：@liuovo/pi-kit。

工具 UI 源自 pi-tidy-tools，保留 Mikey O'Brien 的 MIT 声明。外观与设置面板迁移自 pi-open-tui，保留其 MIT 声明；版本、文件映射及适配说明见 迁移记录。

安装

pi install npm:@liuovo/pi-kit
# 本地开发：
npm ci
pi -e ./index.ts

运行环境：Node.js 22.19.0+、Pi / pi-tui 1.1.0。

项目结构

index.ts                    # 兼容入口，保留现有安装和 -e 路径
extensions/index.ts         # Pi 扩展 factory，装配各模块
src/
├── config.ts               # 配置读写与共享配置类型
├── config/                 # Open TUI 类型、默认值与规范化
├── commands/               # /liuovo 面板事务、FFF 确认与 reload
├── tools/                  # 工具执行与 reasoning 组合、图片生成
├── integrations/pi-fff/    # 可选 FFF 集成
└── ui/
    ├── settings.ts         # 复用上游的统一交互面板
    ├── shell/              # Header、Footer、编辑器、Git、运行环境与遥测
    ├── tools/              # 工具卡片、子调用、摘要、源码与 diff
    ├── interaction/        # TUI 交互生命周期与视口保持
    ├── status/             # 终端标题状态
    └── theme.ts            # UI 语义色与状态样式
themes/                     # Pi 可发现的 JSON 主题资源
vendor/                     # 保留来源的第三方代码
test/                       # 模块测试与宿主集成测试
scripts/                    # 验收与发布包检查
docs/                       # 项目结构与集成约定

两个入口只能加载一个，避免重复注册；模块放置与入口约定见 项目结构说明。

工具 UI 模块

目的优先的紧凑工具展示：第一行是工具与调用目的，第二行是目标与结果摘要。没有整块背景或工具图标，以语义色小圆点表示状态；Edit diff 按需展开。

● codemode 将设计文档与实现保持一致 · 3 calls · 3s
  ● edit 记录目的优先布局与按需展开规则
    docs/architecture.md → +23/-20
  ● edit 只展开 Edit 差异而保持其它输出收起
    src/ui/tools/nested.ts → +1/-1
  ● bash 验证类型检查与回归测试
    npm run check && npm test → done in 2s

• 使用原始工具名 read / edit / bash / codemode。
• 第一行的目的使用正文色；第二行路径/命令弱化，以 → 连接结果。长目标会截短，尽量保留结果后缀。
• 每个工具标题只有一个状态点：成功绿色、失败红色、取消/未完成警告色；运行中的 ● 保持形状不变，约 1.92 秒一个周期沿强调色的明暗明显呼吸，不切换字符、不闪烁、不消失；等待执行时为弱化色。工具名另保留类别色，不需要 Nerd Font。
• 调用次数、耗时单独着色；增删统计使用新增绿、删除红。所有状态都没有整卡底色。
• 所有工具默认显示摘要，Edit 默认只显示 +N/-N，不铺开 diff；Write、Bash 也不默认铺开源码和日志。
• 最终耗时只来自 Pi 的 durationMs；运行估时用单调时钟。活动卡片共用 160ms 刷新器，参数生成、历史恢复与静态卡片不启动动画。
• 原生图片仍由 Pi 显示，遵循 show-images 设置；不改变工具结果、usage 或执行方式。

点击与展开

点击 codemode 卡片，或用 Pi 的工具展开键（默认 Ctrl+O）：有 Edit 时只展开 Edit diff；没有 Edit 时展开所有已记录子工具的内容。

• diff 显示在对应 Edit 的路径与统计下面，带行号；删除行浅红底、新增行浅绿底，行号与增删标记保留红绿前景，代码正文保留原有语法高亮。底色铺满差异区域的行宽（包含软换行）；上下文、标题和整卡不加背景。
• 有 Edit 时，Read、grep/find/ls、Bash、Write 保持摘要；没有 Edit 时，这些子工具展开有界正文，并显示收起时省略的已记录调用。脚本及脚本输出仍不展示。
• 再次点击收起详情，恢复完全相同的摘要布局。
• 缺少历史 diff 显示 Diff not recorded；记录被截断时明确提示。
• 独立工具卡片仍可单独展开内容，例如独立 Read 的行号源码视图；codemode 则按有无 Edit 决定展开范围。
• 点击行为由 Pi 原生工具卡片负责；fullscreen 的键盘与鼠标开合保留视口锚点。

开启“相邻调用分组”只在 codemode 内合并相邻、相同工具、相同目的、同一父级的标题，下面逐项列目标与结果。不跨过其它调用重排，不把不同目的的 Read 合成一条统计。

/liuovo 设置

输入 /liuovo 打开统一的交互式设置面板。面板直接复用 pi-open-tui 的分页组件，支持英文和简体中文；不提供子命令或独立的 Open TUI 命令。

• Tab / Shift+Tab / ← / →：切页；↑ / ↓：选择；Enter / Space：修改；Esc / q：关闭。
• 常规 / General：Open TUI 外观开关、语言、思考预览、内联底栏。
• 外观 / Appearance：图标模式、块状 / 竖线 / 下划线光标。
• 底栏 / Footer：目录、主机、会话名、Git、运行环境、上下文、Token、费用、扩展状态等。
• 遥测 / Telemetry：TPS、TTFT、耗时、Token、停顿、费用速率。
• 工具 / Tools：工具增强开关、目的展示、相邻调用分组、详情密度、第三方工具白名单。
• 集成 / Integration：FFF 状态和恢复指引，以及“配置 FFF / Set up FFF”“恢复 FFF / Restore FFF”。PgUp / PgDn 滚动完整状态；修改 FFF settings 前仍须确认预览。

面板始终可以打开。 工具增强与 Open TUI 外观独立开关，关闭全部功能也不影响 /liuovo。工具增强开关控制原有工具组合、工具卡片、reasoning 采集、标题状态和图片工具；Open TUI 开关控制 Header、Footer、编辑器、思考预览及遥测，不改变工具执行。

显示偏好保存后立即刷新。外观的安装/卸载在关闭面板后执行，避免破坏焦点；光标等偏好可实时预览。工具增强开关在关闭面板后 reload，第三方白名单编辑成功后 reload。FFF 操作会先退出面板再请求确认，成功修改时 reload 一次。保存失败显示错误并保持原值；设置保存在磁盘上后才更新运行状态。

Reason 展示	行为
auto（默认）	工具名后直接显示调用目的；长目的续行
expanded	仅在该工具自身允许展开时显示目的；codemode 内遵循有无 Edit 的展开范围
off	隐藏子工具目的；父卡片的任务标题仍保留

显示与采集分离：基础工具一直要求短 reasoning 参数，执行前剥离；目的展示设为 off 不改 schema、不减少模型上下文。第三方工具不注入此字段。没有 reason 的历史记录正常显示。

密度只影响显式展开的详情预算：normal 最多约 2,000 个视觉行，dense 为 80 行；默认两行摘要不变，密度设置不改变 codemode 的条件展开范围。

配置在 Pi agent 目录的 liuovo.json（通常 ~/.pi/agent/liuovo.json）：

{
  "enabled": true,
  "reasoning": "auto",
  "grouping": true,
  "density": "normal",
  "tools": [],
  "openTui": {
    "enabled": true,
    "settingsLanguage": "en",
    "inlineFooter": false,
    "cursorStyle": "block",
    "icons": { "mode": "auto" },
    "thinkingPeek": { "lines": 1 }
  }
}

tools 是第三方工具名的显式白名单，默认空。加入后获得目的标题/目标摘要，展开时可委托它原本的复杂 renderer；原 renderer 抛错则回退文本。不修改它的执行器、schema、激活或 usage。通过“工具 → 第三方工具”编辑逗号分隔列表；不想协调展示的工具从列表移除。手工修改配置后 /reload。

PI_LIUOVO 仅覆盖工具增强开关，接受 on/off、true/false、yes/no、1/0。启用覆盖时，面板内工具增强开关要求先取消环境覆盖，但显示偏好和 Open TUI 开关仍可修改。PI_CODING_AGENT_DIR 控制 agent 目录；测试可用 PI_LIUOVO_CONFIG 重定向配置。

可选主题

包内附带可选主题 liuovo-claude。通过 Pi 的 /theme 自行选择；不会静默改 settings 或终端字体。system、light、dark 与自定义主题都可以继续使用；两行布局与主题选择是两回事。

Native codemode

保留 builtin:codemode 加载，需要时通过 Pi 工具选择启用，例如把 "+codemode" 合并进 defaultTools。/liuovo → 集成 → 配置 FFF 不会启用 codemode。

Code 卡片的任务标题来自脚本开头的 // reasoning: <goal>；若有 // @options:，reasoning 写在下一行。缺失时使用“执行工具脚本”。Pi 继续拥有 grammar、executor、sandbox、存储、输出保护、取消、激活、codemode.mode、inlineBudget 和计费。

子调用沿真实父子层级排列；只合并相邻的相同工具/目的标题。models.classify / models.generateImages 保留模型引用、原生耗时和 cost，不重复累加 usage。

观察记录有界：每批最多 256 次调用（包含父调用）。摘要保留前 8 个子调用，另保留后续 Edit、最多 3 个后续异常及它们的父项；其它省略数量明确显示。有 Edit 时开合选择同一组摘要，展开只增加 Edit diff；没有 Edit 时展开全部已记录的子调用及有界正文。

子预览最多 2,048 字符/24 源码行，全批最多 32,768 字符；reason/目标/摘要通常限 240 字符。摘要总数与被截短的正文分别保存，避免把预览行数误报为原始结果行数。独立源码视图预处理限 512 KiB / 10,000 行，展开输出仍有视觉行上限。

记录保存到 result details，不改模型结果；恢复历史只用已有记录，不偷偷重读文件。没有保存的 Edit diff 不伪造。未结束的调用标为 incomplete/cancelled，晚到的真实结束事件可以纠正推断状态。RPC/JSON/print 不安装 TUI widget、鼠标或视口 hook。

Optional FFF execution

只支持 Pi 1.1.0 + @ff-labs/pi-fff@0.11.0：

pi install npm:@ff-labs/pi-fff@0.11.0
# 或 pi install -l npm:@ff-labs/pi-fff@0.11.0

/liuovo → 集成 → 配置 FFF 预览并确认 FFF 包过滤修改，reload 一次；不存在 FFF 时不自动安装。FFF 执行公开 grep / find，原生 read 不变；原始 ffgrep / fffind 不直接暴露。命令、flags、自动补全、生命周期与执行元数据保留。使用 FFF 的 tools-and-ui 或 tools-only，不要选冲突的 override。

日志为 settings 同目录的 liuovo.pi-fff.json。移除任一被管理包前先 /liuovo → 集成 → 恢复 FFF；恢复异常按 /liuovo → 集成 提示处理，不伪造或删除未恢复的日志。详见 FFF 文档。

标题状态与图片生成

标题状态：空闲 π、执行 spinner、等待确认/输入 ?、完成 ✓、失败 !、取消 ⏹。以 Pi agent_settled 为结束边界，重试/续跑不断开；仅 TUI 写标题，停用时清理。不要同时启用另一个标题所有者。

generate_image 调用 Pi 原生 ctx.modelRegistry.generateImages()，使用 /login 或 provider 环境认证，保存至 .fleet/images/pi/，返回路径与结构化 {provider, model, images}，不返回 base64；usage 只转发一次。

默认 openrouter/google/gemini-2.5-flash-image。可用 PI_LIUOVO_IMAGE_PROVIDER / PI_LIUOVO_IMAGE_MODEL 或调用参数覆盖，PI_LIUOVO_FLEET_DIR / PI_LIUOVO_BOTS_NAME 控制输出目录。用 models.getAvailableOfType("image") 查模型；内联图片和输入图片编辑仍使用 models.generateImages() 与 image(block)。

开发与验收

npm ci
npm run check
npm test
npm run test:pack
npm run test:host-smoke
npm run test:tui
# 需要 npm 网络访问的隔离 FFF 验收：
npm run test:pi-fff-installed
npm run test:pi-fff-tui
PI_FFF_TUI_MODE=regular npm run test:pi-fff-tui

host smoke 使用 Pi 1.1 的真实加载器、工具与 codemode worker，但模型/图片 provider 是离线替身，不产生费用；覆盖执行、structured result、usage、持久化、HTML、取消和标题状态。test:tui 用真实 Pi CLI + util-linux script(1) 验证 regular/fullscreen 的两行布局、呼吸圆点、红绿 diff 底色、有/无 Edit 的条件展开、Ctrl+O、fullscreen 鼠标点击、即时偏好、reload 与退出。使用隔离配置，不改个人设置。

用真实 renderer 生成视觉审阅：

npx tsx docs/visual-preview.ts > /tmp/liuovo-preview.html

宿主集成见 Pi 1.1 基线，模块划分见 项目结构说明。发布命令为 npm run release（bumpp）。