# Open TUI 迁移记录

## 来源与许可

- 上游：[OldSuns/pi-open-tui](https://github.com/OldSuns/pi-open-tui)
- 源快照：[`766ccab7b40df6fb9682a105a05d3838803c3d4b`](https://github.com/OldSuns/pi-open-tui/tree/766ccab7b40df6fb9682a105a05d3838803c3d4b)，manifest 版本 **0.3.11**。
- 原始 [MIT 许可证](../vendor/pi-open-tui/LICENSE) 随发布包分发。迁移源码标注来源，没有另行注册独立扩展，也不依赖 `pi-open-tui` npm 包。
- 保留上游对 [pi-haiku](https://github.com/nnocte/pi-haiku)、[pi-claude-code-tui](https://github.com/Phoobobo/pi-claude-code-tui)、[pi-zentui](https://github.com/lmilojevicc/pi-zentui) 的致谢。

## 文件与功能映射

上游的 `extensions/open-tui/` 按当前项目职责拆分：

| 上游文件 | 当前实现 | 保留的功能 |
| --- | --- | --- |
| `index.ts` | `src/ui/shell/index.ts` | 会话/消息/模型/工具事件、外观安装清理、设置应用 |
| `config.ts` | `src/config/open-tui.ts`、`src/config.ts` | 默认配置和规范化；持久化统一到 liuovo.json |
| `settings-command.ts` | `src/ui/settings.ts`、`src/commands/liuovo.ts` | 直接复用原分页/选择/键盘/语言组件；命令事务与绘制分离 |
| `header.ts` | `src/ui/shell/header.ts` | Pi logo、模型、思考级别、工作目录、命令提示 |
| `footer.ts` | `src/ui/shell/footer.ts` | 响应式布局、上下文、累计 usage、扩展状态原色、内联布局 |
| `editor.ts` | `src/ui/shell/editor.ts` | 原生 CustomEditor、圆角边框、三种光标、鼠标坐标与输入焦点 |
| `git.ts`、`runtime.ts` | `src/ui/shell/` 下同名文件 | Git 分支/工作树/暂存/分叉/HEAD/tag、50+ 运行环境检测 |
| `telemetry.ts` | `src/ui/shell/telemetry.ts` | TPS、TTFT、耗时、Token、停顿、每百万 Token 费用速率 |
| `peek.ts` | `src/ui/shell/peek.ts` | 隐藏思考区的 0/1/2 行流式尾部预览 |
| `state.ts`、`session-lifecycle.ts` | `src/ui/shell/` 下同名文件 | 展示状态、usage 缓存、会话代际检查 |
| `icons.ts`、`utils.ts` | `src/ui/shell/` 下同名文件 | 上游图标集、格式化、ANSI 清理、宽度预算 |
| `tests/*.test.ts` | `test/open-tui-*.test.ts`、`test/settings-ui.test.ts` | 原有编辑器、底栏、遥测、思考预览和面板回归 |

包注册始终只有 `index.ts` 一条入口，由 `extensions/index.ts` 装配。项目布局规范见 [architecture.md](architecture.md)。

## 有意适配

| 原行为 | 集成后行为 |
| --- | --- |
| 独立设置命令和配置文件 | 唯一 `/liuovo` 打开统一面板，配置仅保存在 `liuovo.json` 的 `openTui` 字段 |
| 四个设置分页 | 原四页保留，增加“工具”和“集成”；FFF 操作复用当前事务保护 |
| 原 liuovo 文本子命令 | 删除解析和补全，无命令兼容分支 |
| 上游配置启动时落盘、保存异常静默忽略 | 启动只读；串行原子合并保存，成功才应用，失败在面板保留原值并显示错误 |
| 外观 enabled 开关 | 只控制 Open TUI；工具增强独立开关；面板不参与任何开关 |
| `agent_end` 完成工作计时 | 使用 Pi 1.1 `agent_settled`，重试/续跑期间不提前停止 |
| 宽松 hasUI 检查 | 仅 `mode === "tui"` 安装终端组件；RPC/JSON/print 不开面板、不改配置、不启动展示定时器 |
| Header 固定提示上游命令 | 固定提示 `/liuovo`，窄屏标题按可见宽度截断 |
| Git 单向 ahead/behind 与不可靠 stash count | 同时解析 ahead/behind；通过 stash 哈希列表计数，保留真实分叉和暂存栈展示 |

不接管 Pi 的 usage 累加、工具执行、模型请求或思考内容记录。遥测的 TPS 使用 provider 报告的输出 Token / 总生成时间；工具执行时间不计入生成速度。`$/M` 是本次运行的标价速率，底栏显示会话累计费用。思考预览只在 Pi 隐藏思考且模型实际流式输出思考时显示，settled 后恢复原生标签。

`icons.mode` 保留 `auto / nerd / unicode / ascii`：auto 根据 TTY/locale 选择，SSH 优先 Unicode；不能检测终端实际安装的字体。Nerd Font 不可用时在面板选择 Unicode 或 ASCII，不修改终端字体。

## 验收与限制

- `npm run check`、`npm test`、`npm run test:pack`。
- `npm run test:host-smoke`：真实 Pi 1.1 加载/执行/usage/取消/回放/标题与面板 FFF 操作。
- `npm run test:tui`：regular/fullscreen，Edit/无 Edit 四组；真实面板改偏好、关闭全部功能、再次打开并分别启用，验证保存、reload 和原卡片交互。
- `npm run test:pi-fff-installed`、`npm run test:pi-fff-tui`、`PI_FFF_TUI_MODE=regular npm run test:pi-fff-tui`：隔离真实安装、自动补全、搜索、会话切换和清理。
- 视觉预览按 [README](../README.md#开发与验收) 从真实 renderer 生成，覆盖新面板与原卡片的亮暗主题。

所有验收使用沙箱配置。不会修改个人 `~/.pi/agent` 设置，不自动禁用用户另行安装的上游扩展。使用本包的 Open TUI 外观时，应避免同时加载另一个 Header/Footer/编辑器所有者。终端字体、IME、硬件光标形状及 Kitty/iTerm 图片协议仍需在实际使用的终端人工确认，PTY 或 HTML 预览不能替代这些确认。