pi-incarnate-ui

pi-incarnate-ui 是 pi-incarnate 的可选固定终端界面。

它使用 Pi 的公开 setFooter() API，把角色呈现和必要的 Pi 运行信息组合成固定底部区域：

• 固定区域严格不超过 6 行，避免压缩对话和输入框。
• 宽终端优先在 4 行预算内等比显示 avatar.png，旁边显示角色、mood、来源和表单状态；没有 PNG 或图片协议不可用时使用 ANSI/TXT 四行采样回退。
• 终端窄于 72 列或低于 20 行时，自动降级为 1 行角色状态加 2 行运行信息。
• off、未启用角色或核心扩展没有响应时完全归还 Pi 默认 Footer，不占用空闲布局。
• 保留工作目录、Git 分支、session 名称、输入/输出与缓存 token、缓存命中率、cost、上下文占用、模型、provider、thinking 和其他扩展状态。
• Pi 默认启动 Header、对话、工具输出和输入框保持原样。
• /incarnate-ui 可按需打开完整头像浮层，Enter、Esc 或 q 关闭；浮层关闭后返回原输入界面。

当前版本为 0.2.0，新增 PNG 等比头像、兼容回退和主题错配时的主信息对比度保护。可使用 pi install npm:pi-incarnate-ui 安装；当前仍不处理与其他自定义 Footer 扩展的共存。

Development

npm install
npm run release:check
npm run test:companion
pi --no-extensions \
  -e /path/to/pi-incarnate/extensions/index.ts \
  -e /path/to/pi-incarnate-ui/extensions/index.ts

test:companion 要求核心仓库位于同级目录 /path/to/pi-incarnate。它加载两个真实扩展入口，验证两种加载顺序、状态生命周期、未知协议版本和缺失另一端的降级。

启动后通过 /incarnate 选择角色。核心扩展只管理人格、角色资源和安全清理；所有终端绘制均由本 UI 扩展负责。未加载 UI 时人格仍然生效，但不显示角色图。PNG 通过 Pi 的 Image 组件使用 Kitty 或 iTerm2 协议渲染，按原始像素尺寸与终端 cell 尺寸等比缩放；Pi 禁用图片或终端不支持时不会输出占位图。

需要查看未经四行采样的完整头像时运行：

/incarnate-ui

查看器只在 TUI 中打开临时居中浮层，使用核心已经验证的 PNG 或清理并限制为最多 48×16 的文本头像数据，不读取角色目录，也不改变 Footer 模式。PNG 在浮层可用空间内等比缩放；文本头像在终端高度不足时可用 ↑ / ↓ 滚动查看全部行。

当前边界

• 只在 TUI 模式设置 Footer；RPC、JSON 和 print 模式不接管表现层。
• 角色状态由版本化的 pi.events 协议传递，UI 不直接读取角色目录。
• compact 使用 3 行布局；auto 和 full 在宽度足够时使用最多 6 行布局；off 或未激活状态不接管 Footer。
• PNG 常驻预览保持宽高比并限制为四行；ANSI/TXT 回退仍从完整文本资源抽样，因此不等同于完整原图。完整内容由按需查看器提供。
• PNG-only 角色在图片协议不可用时降级为紧凑角色状态；建议同时提供 avatar.ansi 或 avatar.txt。
• 完整头像查看器是临时 overlay，不占用常驻布局；无活动头像或非 TUI 模式时只给出提示。
• 当前角色状态仍由 pi-incarnate 按 session 管理；新会话默认关闭，需要重新选择角色，此时显示 Pi 自身的默认 Footer。
• Pi 0.85.0 的公开扩展上下文不暴露通用订阅检测和 auto-compaction 开关；UI 只保留默认 Footer 可公开重建的信息，并沿用 Pi 对 kimi-coding 的已知订阅标记。其他 provider 的内部订阅状态与 auto-compaction 标记不显示。