🛡️ v1.3.1.2: Hardened Python 3.9 Compatibility

This release ensures robust support for Python 3.9 environments and resolves residual TUI focus issues.

✨ Fixes

• Hardened Python 3.9 Compatibility: Switched from modern | type pipes back to standard Union and restored the from __future__ import to ensure full functionality on Python 3.9 (common on macOS default environments).
• TUI Focus Stability: Removed problematic manual focus shifts that caused ValueError crashes during modal dialog transitions.

🛡️ v1.3.1.2: 深度兼容性与稳定性修复

本次更新确保了对 Python 3.9 环境的健壮支持,并彻底解决了 TUI 聚焦相关的残留崩溃问题。

✨ 修复内容

• 增强 Python 3.9 兼容性:将现代的 | 类型符号切换回标准的 Union 语法,并恢复了 from __future__ 导入,确保在 macOS 默认的 Python 3.9 环境中也能 100% 稳定运行。
• TUI 聚焦状态加固:移除了在模态对话框切换时可能引起 ValueError 崩溃的手动聚焦代码。

安装与更新 / Installation & Update

ocs --update

🛠️ v1.3.1.1: Hotfix for Python 3.9 & Focus Issues

This is a hotfix release addressing critical runtime regressions introduced in the previous TUI overhaul.

✨ Fixes

• Python 3.9 Compatibility: Resolved a TypeError on older Python environments (like macOS default 3.9) by adding forward-looking type annotations support.
• TUI Focus Fix: Resolved a ValueError that caused the application to crash when trying to focus a non-focusable container after closing deletion/rename dialogs.

🛠️ v1.3.1.1: Python 3.9 与聚焦问题热修复

本版本为热修复更新,解决了之前 TUI 重构中引入的两个关键运行时回归问题。

✨ 修复内容

• Python 3.9 兼容性修复:通过添加前瞻性类型注解支持,解决了在较旧 Python 环境(如 macOS 默认的 3.9)中出现的 TypeError。
• TUI 聚焦修复:解决了在关闭删除或重命名对话框后,因尝试聚焦不可聚焦容器而导致的 ValueError 应用崩溃。

安装与更新 / Installation & Update

ocs --update

🛡️ v1.3.1.0: Safe Deletion & TUI Stability

This release focuses heavily on user data safety by completely redefining the destructive deletion workflow within the OCS terminal UI.

✨ Highlights

• Safe Deletion Modal: The Ctrl+D shortcut now intelligently triggers an interactive, native-looking two-step confirmation modal. It effectively eliminates the risk of accidental single-keystroke history loss.
• Strict Input Blocking: Introduced a robust global state lock (cond_not_modal) that intercepts and neutralizes unexpected keyboard inputs whenever a secondary dialog is active.
• Ruff AST Polish: A sweeping zero-tolerance lint correction resolving 30+ internal styling and logic parsing warnings.

🛡️ v1.3.1.0: 安全删除拦截与架构加固

本次发布专注于用户数据安全,通过完全重定义 OCS 终端界面中的破坏性删除工作流,解决了单击误删风险。

✨ 核心特性

• 安全删除弹窗:Ctrl+D 快捷键现在会触发一个交互式的、原生风格的两阶段确认弹窗,彻底杜绝了因误触导致历史记录不可逆丢失的风险。
• 全层级按键阻断:引入了强健的全局状态锁(cond_not_modal),确保在任何弹窗开启时,背景列表的滚动与搜索字符输入都会被静默拦截。
• Ruff 代码净化:进行了全量的 Lint 自动修复,解决了 tui.py 中 30 余处内部样式与逻辑解析警告。

安装与更新 / Installation & Update

ocs --update

🚀 OCS v1.3.0.1 (Hotfix / 热更新)

🇺🇸 Fixed

• Fixed an unexpected TypeError: __init__() got an unexpected keyword argument 'left_margin' crash in the TUI renaming modal dialog that occurred exactly upon initial render, caused by improper prompt_toolkit Window border configuration.

🇨🇳 修复

• 紧急修复了 TUI 界面在刚刚启动并调出"重命名会话"模态框时,由于使用了 prompt_toolkit 不支持的非法参数(left_margin)而导致的致命崩溃报错(TypeError)问题。
• 已将代码安全重构为标准的 VSplit 宽度横切安全盒模型布局,确保极高的终端兼容性。

Release v1.3.0.0: Self-Update & Command Reference

[Scroll down for Chinese version / 向下滚动查看中文说明]

This release introduces the highly-requested self-update capability and provides comprehensive command reference documentation for all OCS features.

🚀 Key Features

1. One-Command Self-Update (--update)

Users can now update OCS to the latest version with a single command:

ocs --update

The updater automatically queries the GitHub Releases API, compares versions, and installs the latest release via pip. No manual cloning or script execution required.

2. Complete Command Reference

Both English and Chinese READMEs now include a dedicated "OCS Command Reference" section covering:

• CLI Arguments: ocs, ocs <number>, ocs <session_id>, ocs <number> <path>
• Options: --version, --list, --update, --verbose
• TUI Keyboard Shortcuts: Full table of all interactive navigation and management keys
• Quick Examples: Copy-paste ready commands for every scenario

3. All Previous Features Included

• Native Modal Rename Dialog (v1.2.3.0)
• Precision CJK Alignment (v1.2.2.0)
• Smooth Viewport Scrolling (v1.2.1.0)
• Full-screen interactive TUI with live search (v1.2.0.0)

Install / Update: pip install -U opencode-session-history or simply ocs --update

发布 v1.3.0.0:一键自更新与指令集参考

本版本引入了用户呼声最高的一键自更新能力,并为所有 OCS 功能提供了完整的指令集参考文档。

🚀 关键特性

1. 一键自更新 (--update)

现在只需一条命令即可将 OCS 更新到最新版本:

ocs --update

更新器会自动查询 GitHub Releases API、比对版本号,并通过 pip 安装最新 Release。无需手动克隆仓库或执行安装脚本。

2. 完整指令集参考

中英文 README 现在都包含了专门的 "OCS 指令集参考" 板块,涵盖:

• 命令行参数:ocs、ocs <序号>、ocs <session_id>、ocs <序号> <路径>
• 选项参数:--version、--list、--update、--verbose
• TUI 键盘快捷键:完整的交互导航与管理操作速查表
• 快速示例:每种场景的即用命令

3. 继承全部历史特性

• 原生模态重命名对话框 (v1.2.3.0)
• 精准 CJK 视觉对齐 (v1.2.2.0)
• 平滑视口滚动 (v1.2.1.0)
• 全屏交互式 TUI 与实时搜索 (v1.2.0.0)

安装/更新:pip install -U opencode-session-history 或直接 ocs --update

Release v1.2.3.0: Native Modal Rename Dialog

[Scroll down for Chinese version / 向下滚动查看中文说明]

This milestone release marks a new era for OCS interaction design: full in-app session management without ever leaving the TUI.

🚀 Key Features

1. Native Modal Rename

Replaced the old "exit TUI → command-line input → re-enter TUI" workflow with a stunning floating dialog rendered directly within the TUI.

• Header: Bold Rename Session title on the left, subtle esc hint on the right.
• Body: Full-width text input area with CJK support and cursor navigation.
• Footer: Clean enter submit action guide.

2. Zero-Restart Live Refresh

After submitting a rename, the in-memory session data updates instantly. You'll see the title change in the list within milliseconds—no app restart, no flicker.

3. Layered Rendering Architecture

The TUI layout engine has been upgraded from flat HSplit to FloatContainer, enabling modal overlays. This architectural foundation supports future popup-based management tools.

🛠 Technical Improvements

• Smart Key Isolation: When the rename dialog is active, all global search and navigation keys are automatically disabled, ensuring input focus integrity.
• Enhanced Date Parser: Now gracefully handles millisecond-timestamp strings from legacy data formats.
• Simplified Event Loop: Removed the while True rename loop from cli.py; all rename logic is now fully encapsulated within the TUI.

Install / Update: pip install -U opencode-session-history or ./scripts/install.sh

发布 v1.2.3.0:原生模态重命名对话框

本版本标志着 OCS 交互体验进入了全新的阶段,实现了全流程 TUI 内闭环——你再也不需要退出界面去执行任何管理操作。

🚀 关键特性

1. 原生模态重命名

摒弃了旧的"退出 TUI → 命令行输入 → 重新进入 TUI"的交互方式。现在按 Ctrl+R 会直接在 TUI 内部弹出一个视觉精美的浮层对话框。

• 标题栏:左侧粗体 Rename Session,右侧淡色 esc 提示。
• 输入区域:全宽文本输入框,完整支持中英文混排与光标操作。
• 页脚:简洁的 enter submit 操作引导。

2. 零重启实时刷新

重命名提交后,内存数据实时同步。你会在提交瞬间看到列表标题自动变更——无需重启应用,无闪烁,行云流水。

3. 分层渲染架构

TUI 布局引擎从平坦的 HSplit 升级为 FloatContainer,原生支持模态浮层叠加。这一架构升级为未来增加更多弹出式管理工具奠定了技术基础。

🛠 技术改进

• 智能热键隔离:当重命名对话框激活时,全局搜索和导航键会自动禁用,确保输入焦点完全锁定。
• 增强日期解析:现在能完美兼容旧版数据中的毫秒级时间戳字符串。
• 简化事件循环:移除了 cli.py 中的 while True 重命名循环,所有逻辑已在 TUI 内部闭环。

安装/更新:pip install -U opencode-session-history 或 ./scripts/install.sh

Release v1.2.2.0: Precision CJK Visual Alignment

[Scroll down for Chinese version / 向下滚动查看中文说明]

A targeted visual fix for East Asian (CJK) users, resolving layout misalignment caused by wide characters in terminal environments.

🚀 Key Features

1. Visual Width Alignment (CJK Support)

Replaced naive len() character counting with the get_cwidth visual width algorithm from prompt_toolkit. Chinese characters occupy 2 terminal columns but only count as 1 in Python's len(). This mismatch caused timestamps and message counts to overflow or misalign. Now, regardless of how many CJK characters appear in your session titles, the right-aligned metadata stays pixel-perfect.

2. Overflow Protection

Added safety buffer zones at terminal edges, completely eliminating the issue of timestamps being pushed off-screen on high-DPI displays or narrow terminal windows.

3. Visual Style Refinement

Unified metadata color values to reduce visual noise from non-essential information, keeping focus on session titles.

Install / Update: pip install -U opencode-session-history or ./scripts/install.sh

发布 v1.2.2.0:精准 CJK 视觉对齐

这是一个针对东亚用户(中日韩)的视觉修复版本,解决了终端环境下"宽字符"导致的排版错乱。

🚀 关键特性

1. 精准阔度对齐 (CJK Support)

放弃了传统的 len() 字符计数,改用 prompt_toolkit 的 get_cwidth 视觉阔度算法。中文字符在终端中占据 2 列宽度,但 Python 的 len() 只计为 1,这种不匹配导致了时间戳和消息数的溢出或错位。现在,无论会话标题中包含多少中文字符,右侧元数据都能保持像素级精准对齐。

2. 溢出保护机制

为终端边缘增加了安全缓冲区,彻底杜绝了时间戳在高分屏或窄窗口下被挤出画面的问题。

3. 视觉风格微调

统一了元数据的色值,进一步降低了非核心信息的视觉干扰,让会话标题始终是视觉焦点。

安装/更新:pip install -U opencode-session-history 或 ./scripts/install.sh

Release v1.2.1.0: Viewport Scrolling & Session Stats

[Scroll down for Chinese version / 向下滚动查看中文说明]

This release tackles the core usability pain point of navigating long session lists, and enriches the TUI footer with live statistics.

🚀 Key Features

1. Smooth Viewport Scrolling

Introduced a dynamic viewport algorithm based on item index tracking. Now whether you have 50 or 500 sessions, the visible window automatically follows your cursor. The old "items beyond row 23 are invisible" limitation is gone forever.

2. Live Session Statistics

The footer now displays a real-time [Total: XX sessions] counter on the right side, giving you instant visibility into the historical scale of your current project.

3. Enhanced Navigation

• ↑/↓: Smooth single-item scrolling with automatic viewport follow.
• ←/→: Page skip (20 items per jump) for rapid traversal.
• Unified footer layout with all navigation hints and action shortcuts.

🛠 Performance

• Optimized list rendering with slice-based logic, reducing memory usage for large session histories.
• Fixed metadata parsing errors caused by version number gaps.

Install / Update: pip install -U opencode-session-history or ./scripts/install.sh

发布 v1.2.1.0:视口滚动与会话统计

本版本解决了长列表显示的核心交互痛点,并增强了 TUI 的信息密度。

🚀 关键特性

1. 平滑视口滚动

引入了基于项目索引的动态视口算法。现在即使有上百条历史会话,也可以通过 ↑/↓ 顺滑翻阅,选中项会自动保持在视口内。之前"超过23行不可见"的问题已彻底成为历史。

2. 实时会话统计

在页脚右侧新增了 [Total: XX sessions] 计数,实时反馈当前项目的历史规模。

3. 交互导航优化

• ↑/↓:逐项平滑滚动,选中项自动保持在视口可见区域。
• ←/→:大跨度跳页(每次跳转20条),快速穿越历史。
• 重塑了页脚布局,整合了导航说明和操作快捷键提示。

🛠 性能改进

• 优化了列表渲染切片逻辑,极大减少了长列表下的内存占用。
• 修复了版本号跨度跳跃导致的元数据读取异常。

安装/更新:pip install -U opencode-session-history 或 ./scripts/install.sh

Release v1.2.0.0: The TUI Evolution / TUI 交互革命

[Scroll down for Chinese version / 向下滚动查看中文说明]

This milestone release transforms OCS into a fully interactive terminal application, providing a premium experience that matches the OpenCode native feel.

🚀 Key Features

1. Modern TUI Interface

A full-screen interactive selector powered by prompt_toolkit. No more static lists—enjoy a fluid, responsive experience.

2. Intelligent Live Search

Real-time filtering as you type. Whether you remember a keyword from the title, the session ID prefix, or just the index number, OCS finds it instantly.

3. Dual-Line Clean Layout

We've implemented a premium dual-line structure:

• Top Line: Human-readable title, index, and activity time.
• Bottom Line: Technical Session ID (indented) to keep the interface clean and avoid horizontal overflow.

4. Date Clustering

Sessions are automatically grouped by date (e.g., Today, Yesterday, Tue Apr 07 2026), making it effortless to find your most relevant work.

5. In-Place Session Management

Take control of your history without leaving the app:

• Ctrl+D (Delete): Instantly remove stale or redundant sessions from your local database.
• Ctrl+R (Rename): Quickly rename any session to clarify your workflow context.

6. Flexible Selection Logic

• Use Arrow Keys to navigate and Enter to attach.
• Directly type a Number or Session ID and hit Enter to jump instantly.

v1.2.0.0: TUI 交互革命

本次里程碑更新将 OCS 彻底进化为一个功能完备的全屏终端交互程序,提供与 OpenCode 原生体验一致的顶级感受。

🚀 核心特性

1. 现代化 TUI 界面

基于 prompt_toolkit 构建的全屏交互选择器。告别静态列表,享受丝滑响应的终端应用体验。

2. 智能实时搜索 (Live Search)

输入即过滤。无论你记得标题关键字、Session ID 前缀,还是仅仅想输入序号,OCS 都能瞬间锁定目标。

3. 双行极致排版

我们采用了全新的双行结构:

• 首行:展示序号、人类可读的标题以及活跃时间,保持视觉重心稳固。
• 次行:缩进展示技术性的 Session ID,完美规避长字符导致的排版错乱。

4. 自动日期聚类

会话按日期自动分组(如:Today, Yesterday, 2026年4月7日 等),让寻找历史记录变得直观高效。

5. 原位会话管理

无需退出程序即可深度治理历史:

• Ctrl+D (删除):秒删陈旧或无意义的实验记录,保持数据库纯净。
• Ctrl+R (重命名):随时修改会话标题,精准标记你的开发上下文。

6. 混合导航逻辑

• 使用 方向键 自由挑选并回车确认。
• 直接在提示符处输入 序号 或 Session ID 并回车,一秒进入现场。

Note: This update requires prompt_toolkit. It will be automatically installed when you update via our install scripts.
注意:本次更新引入了 prompt_toolkit 依赖。使用我们的安装脚本进行更新时会自动为您部署。

Release v1.1.0.0: The Robust Core Update

[Scroll down for Chinese version / 向下滚动查看中文说明]

This release supercharges the core capabilities of OpenCode Session History (OCS) while strictly maintaining our beloved "single-file CLI" lightweight architecture. We've replaced fragile guesswork with robust systems, expanding from a simple tracking script into a battle-tested historical navigator.

⚡️ Key Enhancements (What's New)

1. Zero-Config Port Detection (lsof Fallback)

Game Changer: You no longer must start OpenCode with an explicit --port flag.
If --port is missing from your process command, OCS will now dynamically execute a lightweight lsof TCP snapshot under the hood to accurately sniff the exact active listening port of your backend server.

2. Standardized CLI Interface

OCS now behaves like a true, standard terminal utility. We've introduced a robust argparse foundation:

• ocs --list (-l): Print all matched historical sessions and quietly exit (useful for pure dashboarding without attaching).
• ocs --verbose (-v): Enable raw diagnostic output. Wondering why OCS told you "No server found"? Run with -v to see the exact CWD mismatches, process scans, and SQLite parsing logs.
• ocs --help / ocs --version: Standard informational flags.

3. Fortified Quality & Testing

• Unit tests skyrocketed from 22 to 58 deterministic coverage tests.
• Replaced legacy syntax workflows with strict Ruff static typing and AST lint checks built deeply into the GitHub CI pipeline.

It's time to upgrade! Enjoy the smoothest recovery flow yet!

Release v1.1.0.0: 核心重构与增强(坚如磐石)

在严格保持我们秉承的"单文件暴力美学"和极轻量级架构的前提下,本次更新为 OCS 注入了真正的工业级鲁棒性。我们将一个简单的追踪脚本,武装成了久经沙场考验的开发利器。

⚡️ 核心特性升级

1. 端口零配置探测 (lsof 绝地反击)

最大痛点解除:你再也不被强制要求启动 OpenCode 时必须携带 --port 参数了!
当系统发现你的守护进程未显式标注端口时,OCS 底层会自动触发一个微秒级的 lsof TCP 协议快照,精准嗅探并提权抓取该服务所在的实际通讯端口。

2. 标准化 CLI 交互界限

OCS 彻底抛弃了纯手工拦截,引入了极为标准的命令行交互体系:

• ocs --list (-l):静默列出当前所有的历史会话大盘并退出(再也不用强迫选择序号了)。
• ocs --verbose (-v):全链路诊断模式。当你再次遇到"找不到可用服务器"时,只需带上 -v 标志,系统会将它所有的 CWD 匹配记录、数据库查询底单和扫描记录打印至 stderr,一目了然。
• ocs --help / ocs --version:常规标准属性宣告。

3. 铁血测试与工程规范

• 单元测试由最初的 22 个大幅扩充至 58 个,几乎防住了全链路的所有边缘边界。
• 摒弃了过期的代码格式,全面将 Ruff (类型及 AST 深层检查)深度整合进了全自动的 CI / CD 管线中。

去体验前所未有的顺滑恢复流程吧!升级愉快!