pi-one-ui 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-09-06
+
+### Added
+
+- Built-in `/effort` command for selecting the thinking effort level (interactive picker, argument autocomplete, and model-clamping feedback), gated by `renderer.enableEffortCommand` (default `true`) and toggleable from the `/oneui` Features section. Replaces the need for a standalone local effort extension — remove any self-installed `/effort` extension to avoid duplicate command registration.
+- The `/oneui` settings panel overlay placement is now configurable via the optional top-level `panel` key in `pi-one-ui.json` (`anchor`, `width`, `maxHeight`, `margin`), replacing the previously hardcoded `top-center`/`85%`/`90%` layout. Invalid values fall back to the defaults, and edits apply the next time the panel opens.
+
+## [0.6.0] - 2026-09-05
+
+### Removed
+
+- Removed the `colorSource` (`theme`/`terminal`) concept from the Editor, user messages, WorkingLine, selector borders, and Footer. Colors are now always rendered with theme semantics: configured `colors.*` values resolve as theme tokens (ANSI names such as `red` map to semantic tokens like `error`), while hex, 256-color indexes, and `fg:`/`bg:` prefixes still render fixed terminal colors.
+- Removed the terminal-only adaptive border ladder and the Color source setting from `/oneui`.
+
+### Changed
+
+- Adaptive Editor borders now prefer the per-level `colors.editorThinking*` configuration, then Pi's native effort coloring, then the default border; thinking labels keep following the border in adaptive mode.
+
+### Migration
+
+- Existing `colorSource` fields in `~/.pi/agent/pi-one-ui.json` are ignored at load time and not rewritten. Configurations that relied on `terminal` fixed colors should move those `colors.*` values to hex, a 256-color index, or an `fg:`/`bg:` prefix; ANSI color names now resolve to theme semantic tokens. See [docs/editor-colors.md](./docs/editor-colors.md) for the full color field reference.
+
 ## [0.5.1] - 2026-09-05
 
 ### Changed
@@ -93,7 +115,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - Reduced rendering lag when expanding settled tool groups by reusing cached child output.
 
-[Unreleased]: https://github.com/kerolt/pi-one-ui/compare/v0.5.1...HEAD
+[Unreleased]: https://github.com/kerolt/pi-one-ui/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/kerolt/pi-one-ui/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/kerolt/pi-one-ui/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/kerolt/pi-one-ui/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/kerolt/pi-one-ui/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/kerolt/pi-one-ui/compare/v0.3.1...v0.4.0

package/README.en.md

@@ -6,43 +6,44 @@
 
 [简体中文](./README.md) | English
 
-`pi-one-ui` is a unified TUI extension package for [Pi](https://pi.dev). It started as an effort to build a simple and polished terminal interface by combining, at the source level:
+`pi-one-ui` is a unified TUI extension package for [Pi](https://pi.dev), designed to deliver a clean, beautiful, and efficient terminal experience. It originated as a source-level combination of:
 
-- the terminal shell capabilities of [pi-zentui](https://github.com/lmilojevicc/pi-zentui)
+- the terminal shell and layout capabilities of [pi-zentui](https://github.com/lmilojevicc/pi-zentui)
 - the conversation rendering and productivity features of [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions)
 
-The result is a single installable and configurable Pi package that continues to evolve through module refactoring, tighter ownership, and independent improvements.
+The result is a single installable and configurable Pi package that continues to evolve through architectural refactoring, strict boundary ownership, and ongoing optimization.
 
 ## Features
 
 ### Unified interface layout
 
-`pi-one-ui` organizes the Pi interface into the following layouts:
+`pi-one-ui` organizes the Pi interface into a clean hierarchy:
 
 ```text
 Header → Context → WorkingLine → Editor → Footer
 ```
 
-- **Header**: startup information, logo, and shortcut hints.
-- **Context**: the conversation area, including user messages, assistant messages, thinking, tools, diffs, Markdown, and summaries.
-- **WorkingLine**: working state, spinner, token/thought/elapsed information, live output rate, and turn summaries.
-- **Editor**: input editor, completion, metadata, and the Minimalist style (Pi native is one toggle away).
-- **Footer**: current directory, Git, runtime, token, cost, and extension status information.
-- **Overlay**: temporary interfaces such as the settings panel and Context Inspector, managed by a shared OverlayManager.
+- **Header**: Startup information, logo, and shortcut hints.
+- **Context**: Conversation content area, including user messages, assistant messages, thinking blocks, tool calls, diffs, Markdown, and turn summaries.
+- **WorkingLine**: Working state indicator, spinner, token/thought/elapsed statistics, live output throughput, and turn summaries.
+- **Editor**: Input editor, completion menu, metadata display, and the Minimalist style (with effortless toggle to Pi native).
+- **Footer**: Current directory, Git status, runtime info, token/cost tracking, and extension statuses.
+- **Overlay**: Temporary views such as the settings panel and Context Inspector, managed centrally by OverlayManager.
 
 ### Built-in functionality
 
 | Feature                | Description                                                                                 | Entry point       |
 | ---------------------- | ------------------------------------------------------------------------------------------- | ----------------- |
-| Unified settings panel | Organizes settings by Header, Context, WorkingLine, Editor, Footer, and Features            | `/oneui`          |
-| Context Inspector      | Shows context usage and previews the system prompt, memory, skills, tools, and messages     | `/context`        |
-| Session reference      | Searches previous Pi sessions or SubAgents and injects their useful context                 | `@` completion    |
-| Subagent autocomplete  | Completes SubAgent names and delegation hints                                               | `@` completion    |
-| Tool / Diff renderer   | Provides unified rendering for tool calls, results, collapsed content, and Edit/Write diffs | Automatic         |
-| Subagent live renderer | Preserves pi-subagents' dedicated progress cards and keeps them out of generic tool groups  | Automatic         |
-| Markdown enhancement   | Adds Mermaid, admonitions, URL linking, and related rendering improvements                  | Automatic         |
-| Built-in themes        | Provides CC Dark and CC Light themes                                                        | `/theme`          |
+| Unified settings panel | Centrally manages settings for Header, Context, WorkingLine, Editor, Footer, and Features    | `/oneui`          |
+| Context Inspector      | Shows context usage and previews system prompt, memory, skills, tools, and message contents | `/context`        |
+| Session reference      | Searches previous Pi sessions or subagents and injects their relevant context               | `@` completion    |
+| Subagent autocomplete  | Provides subagent name completion and delegation hints                                      | `@` completion    |
+| Tool / Diff renderer   | Unified rendering for tool executions, results, collapsible blocks, and Edit/Write diffs   | Automatic         |
+| Subagent live renderer | Preserves subagents' dedicated progress cards without grouping them into generic tool calls | Automatic         |
+| Markdown enhancement   | Adds Mermaid diagrams, admonitions, clickable URL linking, and rendering improvements       | Automatic         |
+| Built-in themes        | Includes CC Dark and CC Light themes                                                        | `/theme`          |
 | Compatibility aliases  | Optionally provides common command aliases                                                  | `/clear`, `/exit` |
+| Effort command         | Interactively or directly switch the active model's thinking effort level                   | `/effort`         |
 
 ## Quick start
 
@@ -77,13 +78,22 @@ Then open the unified settings panel:
 
 ## Configuration
 
-The configuration file is located at:
+### Configuration methods
+
+`pi-one-ui` uses a single canonical v1 configuration file:
 
 ```text
 ~/.pi/agent/pi-one-ui.json
 ```
 
-Using the `/oneui` settings panel is recommended. The panel uses a top-centered layout, stays open while Editor enablement or style changes are applied, restores focus after Editor replacement, and restores the effective list value when persistence fails. The current configuration uses the v1 structure, for example:
+You can configure the extension in two ways:
+
+1. **Interactive settings panel (recommended)**: Run `/oneui` in Pi to adjust common component toggles, styles, and border modes via a visual menu. Changes take effect immediately and are persisted automatically.
+2. **Direct JSON editing**: Advanced users can edit the JSON configuration file directly for finer-grained control. After saving edits, run `/reload` in Pi to apply changes. When the file does not exist, safe runtime defaults are used in memory.
+
+### Basic configuration example
+
+Below is a typical v1 configuration structure:
 
 ```json
 {
@@ -91,55 +101,60 @@ Using the `/oneui` settings panel is recommended. The panel uses a top-centered
   "components": {
     "editor": {
       "style": "on",
-      "colorSource": "theme",
       "borderColorMode": "static"
     },
-    "userMessages": {
-      "enabled": true,
-      "style": "framed"
+    "footer": {
+      "style": "starship"
     },
     "workingLine": {
       "enabled": true
     },
-    "footer": {
-      "style": "starship"
+    "userMessages": {
+      "enabled": true,
+      "style": "framed"
     }
   },
   "renderer": {
     "mode": "on",
     "diffViewMode": "auto"
+  },
+  "panel": {
+    "anchor": "top-center",
+    "width": "85%",
+    "maxHeight": "90%",
+    "margin": { "top": 6, "right": 1, "bottom": 1, "left": 1 }
   }
 }
 ```
 
-The Editor keeps a single `minimalist` decoration style controlled by `style`: `on` enables the Minimalist decoration, `off` restores Pi's native editor (the border follows the theme and effort coloring by default; when `colors.editorBorder` is explicitly configured, the off mode applies that color through `colorSource`, overriding the native effort coloring). Legacy configurations migrate automatically: `enabled: false` becomes `style: "off"`, and `opencode`/`minimalist` become `style: "on"`; the `styles.opencode` block and the retired `opencode-copy-friendly`/`accent-rail` styles are ignored. `borderColorMode` supports `static` (fixed `colors.editorBorder`) and `adaptive` (border shifts with the effort level); `colorSource` supports `theme` (colors resolved through the active Pi theme tokens) and `terminal` (fixed terminal colors). When `cwd`, the model label, or the static border are not explicitly configured, the theme's `cwd`/`editorModel`/`editorBorder` tokens are used first (they may point to `vars` variables or hex values), falling back to Pi's native defaults when the theme does not define them; the terminal source falls back to Pi's native colors as well when unconfigured (only an explicit terminal color name or hex is rendered fixed). Context-usage information is presented by Footer.
+### Advanced configuration & documentation guide
 
-The WorkingLine token segment appends live output throughput, such as `⚡12 tok/s`, after a model response has run for at least 500ms. Throughput is calculated independently for the current response and resets on the next `turn_start`; disabling the token segment hides it as well.
+To keep the configuration section clean and focused, in-depth options, template variables, and color references are organized in dedicated documentation:
 
-Available layout and renderer options may change between versions, so prefer configuring them through `/oneui`.
-
-### Canonical configuration policy
-
-`pi-one-ui` reads and writes only:
-
-```text
-~/.pi/agent/pi-one-ui.json
-```
-
-It does not automatically read, merge, or migrate historical configuration files, and it does not parse legacy flat fields or old style identifiers. If the file does not exist, runtime defaults are used in memory. The file is created only after the first settings change through `/oneui`. All persisted changes use the current v1 `components` and `renderer` structure.
+- **Component options & layout customization**: see [Editor & Footer Configuration Guide (docs/configuration.md)](./docs/configuration.md)
+  - **Editor**: Configure `style` (`on` for Minimalist decoration / `off` for Pi native), `borderColorMode` (`static` or `adaptive` to thinking effort), `modelLabel`, and granular Minimalist displays (directory path format, session name, timer, cost, Git status, etc.).
+  - **Footer**: Starship-style layout powered by format templates (`$cwd`, `$git_branch`, `$tokens`, `$cost`, etc.), individual `segments` toggles, customizable separators, and context-usage indicators (gauge or text).
+  - **WorkingLine**: Built-in live output throughput tracking (appends e.g. `⚡12 tok/s` when a model response runs for at least 500ms, reset per turn).
+- **Settings panel (`/oneui`) customization**: the optional top-level `panel` section controls the overlay placement and size (all fields default to the values shown in the example above).
+  - `anchor`: one of `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `top-center`, `bottom-center`, `left-center`, `right-center`.
+  - `width` / `maxHeight`: absolute column/row counts, or percentage strings like `"85%"`.
+  - `margin`: distance from the terminal edges — either a single number for all sides, or an object with per-edge `top`/`right`/`bottom`/`left` values.
+  - Saved changes apply the next time `/oneui` opens; no `/reload` needed.
+- **Color system & theme customization**: see [Editor Colors Reference (docs/editor-colors.md)](./docs/editor-colors.md)
+  - All colors resolve through unified theme semantics. Configured `colors.*` values resolve as theme tokens (adapting automatically across themes), while ANSI names map to semantic tokens (e.g. `red` to `error`). Fixed terminal colors can be specified using hex codes, 256-color indexes, or `fg:`/`bg:` prefixes.
+  - Full support for adaptive thinking-effort border colors (from Low to Max) and labels.
+- **Migration from legacy versions**: Field cleanups from 0.5.x/0.6.0 (such as merging `opencode` into `minimalist`, or removing `colorSource`) are covered in [docs/configuration.md: Changes and Migration](./docs/configuration.md#6-变更与迁移).
 
 ## Upstream origins and project evolution
 
-`pi-one-ui` originally combined source from the following open-source projects. Many thanks to their maintainers and contributors for providing the initial foundation.
+`pi-one-ui` was originally built upon source code from two open-source projects. We express our sincere appreciation to both upstream projects and their contributors:
 
 | Upstream project                                                | Capabilities incorporated into `pi-one-ui`                                                 | Reference baseline        |
 | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------- |
-| [pi-zentui](https://github.com/lmilojevicc/pi-zentui)           | Starship-style Footer, Opencode-style Editor, layouts, and shell capabilities              | v0.21.0, commit `5341b38` |
+| [pi-zentui](https://github.com/lmilojevicc/pi-zentui)           | Starship-style Footer, Editor layouts, and shell interaction capabilities                  | v0.21.0, commit `5341b38` |
 | [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions) | Claude Code-style Context renderer, Tool/Diff rendering, Context Inspector, and references | v0.8.67, commit `dba37e5` |
 
-Production code lives in `extensions/`. The project has since unified its entry point, configuration storage, lifecycle, layout ownership, overlays, and input routing. The current implementation is no longer equivalent to either upstream project and does not automatically track upstream changes.
-
-The upstream projects provided the original foundation. Continued development focuses on turning these capabilities into one coherent product with clear seams and sustainable maintenance.
+Production code lives in `extensions/`. `pi-one-ui` has unified the composition entry point, configuration storage, lifecycle management, layout ownership, overlay orchestration, and input routing. The project now evolves independently and no longer tracks upstream changes directly.
 
 See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed module boundaries, event flow, and ownership conventions.
 

package/README.md

@@ -6,43 +6,44 @@
 
 简体中文 | [English](./README.en.md)
 
-`pi-one-ui` 是一个面向 [Pi](https://pi.dev) 的统一 TUI 扩展包。项目的初衷是希望打造一个简单美观的 TUI 界面，最初通过源码级融合，将：
+`pi-one-ui` 是面向 [Pi](https://pi.dev) 的统一 TUI 扩展包，旨在打造简洁、美观且高效的终端交互界面。项目最初通过源码级融合，将：
 
-- [pi-zentui](https://github.com/lmilojevicc/pi-zentui)`pi-zentui` 的终端外壳能力
+- [pi-zentui](https://github.com/lmilojevicc/pi-zentui) 的终端外壳与布局能力
 - [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions) 的对话内容渲染及生产力功能
 
-整合到同一个可安装、可配置的 Pi package 中，并在此基础上持续进行模块重构、职责收敛和独立优化。
+整合为开箱即用、统一可配置的单一扩展包，并在此基础上持续进行模块重构、职责收敛和体验优化。
 
 ## 特性
 
 ### 统一的界面布局
 
-`pi-one-ui` 将 Pi 的交互界面划分为以下布局：
+`pi-one-ui` 将 Pi 的交互界面划分为以下布局层级：
 
 ```text
 Header → Context → WorkingLine → Editor → Footer
 ```
 
 - **Header**：启动信息、Logo 和快捷键提示。
-- **Context**：对话内容区，包含用户消息、Assistant 消息、Thinking、Tool、Diff、Markdown 和 Summary。
-- **WorkingLine**：工作状态、spinner、token/thought/elapsed、实时输出速率和回合摘要。
-- **Editor**：输入编辑器、completion、metadata，以及 Minimalist 样式（可切换 Pi 原生）。
-- **Footer**：目录、Git、runtime、token、cost 和扩展状态等信息。
-- **Overlay**：设置面板、Context Inspector 等临时浮层由统一的 OverlayManager 管理。
+- **Context**：对话内容区，包含用户消息、Assistant 消息、Thinking 思考过程、Tool 执行、Diff 对比、Markdown 及回合摘要。
+- **WorkingLine**：工作状态指示、Spinner、Token/思考时长统计、实时吞吐速率及回合摘要。
+- **Editor**：输入编辑器、补全建议、元数据展示及 Minimalist 极简样式（支持一键切换 Pi 原生）。
+- **Footer**：工作目录、Git 状态、运行时信息、Token/费用统计及扩展状态等。
+- **Overlay**：设置面板、Context Inspector 等临时浮层，统一由 OverlayManager 调度管理。
 
 ### 内置功能
 
 | 功能                  | 说明                                                                   | 入口              |
 | --------------------- | ---------------------------------------------------------------------- | ----------------- |
-| 统一设置面板          | 按 Header、Context、WorkingLine、Editor、Footer 和 Features 组织设置   | `/oneui`          |
-| Context Inspector     | 查看上下文占用，并预览 System prompt、Memory、Skills、Tools 和消息内容 | `/context`        |
-| Session reference     | 搜索并注入历史 Pi session 或 SubAgent 的有效上下文                     | `@` 补全          |
-| Subagent autocomplete | 提供 SubAgent 名称补全和委派提示                                       | `@` 补全          |
-| Tool / Diff renderer  | 工具调用、结果、折叠内容和 Edit/Write diff 的统一展示                  | 自动生效          |
-| Subagent live renderer | 保留 pi-subagents 专用进度卡，并避免纳入通用工具分组                    | 自动生效          |
-| Markdown enhancement  | 支持 Mermaid、提示框和 URL 链接化等增强渲染                            | 自动生效          |
-| Built-in themes       | 提供 CC Dark 和 CC Light 主题                                          | `/theme`          |
+| 统一设置面板          | 集中管理 Header、Context、WorkingLine、Editor、Footer 等组件及功能设置   | `/oneui`          |
+| Context Inspector     | 查看上下文占用，并预览 System prompt、Memory、Skills、Tools 及消息内容 | `/context`        |
+| Session reference     | 搜索并引用注入历史 Pi 会话或 Subagent 的有效上下文                     | `@` 补全          |
+| Subagent autocomplete | 提供 Subagent 名称补全与委派提示                                       | `@` 补全          |
+| Tool / Diff renderer  | 工具调用、执行结果、折叠内容与 Edit/Write Diff 的统一美化渲染          | 自动生效          |
+| Subagent live renderer | 保留 subagents 专用进度卡片，避免混入通用工具分组                    | 自动生效          |
+| Markdown enhancement  | 支持 Mermaid 图表、提示框与 URL 链接化等增强渲染                       | 自动生效          |
+| Built-in themes       | 内置 CC Dark 和 CC Light 主题                                          | `/theme`          |
 | Compatibility aliases | 可选提供常用命令别名                                                   | `/clear`、`/exit` |
+| Effort command        | 交互式或直接切换当前模型的 Thinking 思考档位                          | `/effort`         |
 
 ## 快速开始
 
@@ -77,14 +78,22 @@ pi install git:github.com/kerolt/pi-one-ui
 
 ## 配置
 
-配置文件位于：
+### 配置方式
+
+`pi-one-ui` 统一使用 Canonical v1 格式的配置文件：
 
 ```text
 ~/.pi/agent/pi-one-ui.json
 ```
 
+提供两种配置途径：
+
+1. **交互式设置面板（推荐）**：在 Pi 会话中运行 `/oneui`，即可在可视化面板中即时调整常用组件开关、样式和边框模式。修改即刻生效并自动持久化。
+2. **手动编辑配置文件**：高级用户可直接编辑 JSON 配置文件以启用更多细粒度选项。修改保存后，在 Pi 中执行 `/reload` 即可生效。文件不存在时将直接使用内置默认值。
+
+### 基础配置示例
 
-推荐通过 `/oneui` 设置面板修改配置。面板采用更靠近顶部的居中布局；切换 Editor 开关、颜色源或边框模式时会保持打开并在 Editor 替换后恢复焦点，持久化失败时则恢复列表中的有效旧值。当前配置仍使用 v1 结构，例如：
+以下为一个典型的 v1 配置文件结构：
 
 ```json
 {
@@ -92,57 +101,62 @@ pi install git:github.com/kerolt/pi-one-ui
   "components": {
     "editor": {
       "style": "on",
-      "colorSource": "theme",
       "borderColorMode": "static"
     },
-    "userMessages": {
-      "enabled": true,
-      "style": "framed"
+    "footer": {
+      "style": "starship"
     },
     "workingLine": {
       "enabled": true
     },
-    "footer": {
-      "style": "starship"
+    "userMessages": {
+      "enabled": true,
+      "style": "framed"
     }
   },
   "renderer": {
     "mode": "on",
     "diffViewMode": "auto"
+  },
+  "panel": {
+    "anchor": "top-center",
+    "width": "85%",
+    "maxHeight": "90%",
+    "margin": { "top": 6, "right": 1, "bottom": 1, "left": 1 }
   }
 }
 ```
 
-Editor 只保留 `minimalist` 一种装饰样式，通过 `style` 开关控制：`on` 启用 Minimalist 装饰，`off` 恢复 Pi 原生编辑器（边框默认跟随主题与 effort 变色；若显式配置了 `colors.editorBorder`，off 模式下也会按 `colorSource` 应用该颜色，覆盖原生 effort 变色）。旧配置的 `enabled: false` 会迁移为 `style: "off"`，`opencode`/`minimalist` 会迁移为 `style: "on"`，`styles.opencode` 嵌套配置与 `opencode-copy-friendly`、`accent-rail` 一并失效。`borderColorMode` 支持 `static`（固定 `colors.editorBorder`）与 `adaptive`（边框随 effort 档位变化）；`colorSource` 支持 `theme`（颜色取当前主题 token）与 `terminal`（固定终端色）。cwd、模型名与边框（static）未显式配置时优先使用主题的 `cwd`/`editorModel`/`editorBorder` token（可指向 vars 变量或 hex），主题未定义则回落 Pi 原生默认；terminal 源未配置时同样回落 Pi 原生颜色（配置了终端色名/hex 才固定渲染）。上下文占用相关信息由 Footer 统一展示。
+### 深度配置与文档指引
 
-WorkingLine 的 token segment 会在一次模型响应持续至少 500ms 后追加实时输出速率，例如 `⚡12 tok/s`。速率按当前响应独立计算，在下一次 `turn_start` 时重置；关闭 token segment 时也会一并隐藏。
+各项组件开关、模板变量与颜色字段的完整规范拆分收录于独立文档中，便于按需查阅：
 
-不同布局和渲染器的可用选项会随版本变化，建议优先使用 `/oneui` 面板进行配置。
-
-### Canonical 配置约定
-
-`pi-one-ui` 只读取和写入：
-
-```text
-~/.pi/agent/pi-one-ui.json
-```
-
-不会自动读取、合并或迁移其他历史配置文件，也不会解析旧版扁平字段和旧 style 名称。配置文件不存在时，运行时直接使用内置默认值；首次通过 `/oneui` 修改设置时才创建文件。所有持久化修改统一写入当前 v1 的 `components` 和 `renderer` 结构。
+- **组件开关与排版定制**：详见 [Editor 与 Footer 配置指南 (docs/configuration.md)](./docs/configuration.md)
+  - **Editor**：支持 `style`（`on` 极简装饰 / `off` 原生）、`borderColorMode`（固定色 / 思考档位自适应）、`modelLabel` 及 Minimalist 装饰细节（目录层级、会话名、耗时、费用、Git 状态等）。
+  - **Footer**：支持 Starship 风格排版，提供丰富的模板变量（`$cwd`、`$git_branch`、`$tokens`、`$cost` 等），支持通过 `format` 自定义或通过 `segments` 控制各段开关，并可自由配置上下文占用率的展示形式（gauge / text）。
+  - **WorkingLine**：内置实时输出速率检测（单次响应持续 >=500ms 自动追加如 `⚡12 tok/s`，按回合独立重置）。
+- **设置面板（`/oneui`）定制**：通过顶层 `panel` 字段控制浮层位置与尺寸，全部字段可省略（缺省值见上文示例）。
+  - `anchor`：锚点，支持 `center`、`top-left`、`top-right`、`bottom-left`、`bottom-right`、`top-center`、`bottom-center`、`left-center`、`right-center`。
+  - `width` / `maxHeight`：列数 / 行数，或 `"85%"` 形式的百分比字符串。
+  - `margin`：距终端边缘的外边距，可以是四边统一数字，也可以是按 `top`/`right`/`bottom`/`left` 分别配置的对象。
+  - 修改保存后下次打开 `/oneui` 即生效，无需 `/reload`。
+- **颜色体系与主题定制**：详见 [Editor 颜色配置说明 (docs/editor-colors.md)](./docs/editor-colors.md)
+  - 所有颜色统一按 Theme 语义解释，优先解析为当前主题语义 Token（随主题自动切换），ANSI 色名自动映射为语义色（如 `red` 对应 `error`）；如需固定色彩，可直接指定 Hex、256 色索引或 `fg:`/`bg:` 前缀。
+  - 支持完整的 Thinking 思考档位（Low 至 Max）自适应边框与标签分级配色。
+- **历史版本迁移**：旧版升级带来的字段收敛（如 `opencode` 样式统一合并入 `minimalist`、`colorSource` 双模式移除等）参见 [docs/configuration.md 变更与迁移节](./docs/configuration.md#6-变更与迁移)。
 
 ## 上游来源与项目演进
 
-`pi-one-ui` 以以下两个开源项目的源码为初始基础，并对它们进行源码级融合。在此再次感谢两个上游项目及其贡献者，他们为 `pi-one-ui` 提供了最初的实现基础。
+`pi-one-ui` 最初以两个开源项目的源码为基础进行整合。由衷感谢两个上游项目及其贡献者的出色工作：
 
-| 上游项目                                                        | 融入 `pi-one-ui` 的主要能力                                                | 参照baseline              |
+| 上游项目                                                        | 融入 `pi-one-ui` 的主要能力                                                | 参照 Baseline              |
 | --------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------- |
-| [pi-zentui](https://github.com/lmilojevicc/pi-zentui)           | Starship 风格 Footer、Opencode 风格 Editor、布局和 shell 能力              | v0.21.0，commit `5341b38` |
-| [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions) | Claude Code 风格 Context renderer、Tool/Diff、Context Inspector 和引用功能 | v0.8.67，commit `dba37e5` |
-
-融合后的生产代码位于 `extensions/`。项目已经在原始实现之上统一入口、配置存储、生命周期、Layout ownership、Overlay 和输入路由，并会继续独立演进；当前实现不再等同于任一上游项目，也不会自动跟随上游同步。
+| [pi-zentui](https://github.com/lmilojevicc/pi-zentui)           | Starship 风格 Footer、Editor 基础布局与 Shell 交互能力                      | v0.21.0，commit `5341b38` |
+| [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions) | Claude Code 风格 Context 渲染器、Tool/Diff 视图、Context Inspector 与会话引用 | v0.8.67，commit `dba37e5` |
 
-感谢两个上游项目及其贡献者。它们为 `pi-one-ui` 提供了最初的实现基础，而本项目后续的工作重点是将这些能力收敛为一个边界清晰、可持续维护的统一产品。
+融合后的生产代码位于 `extensions/`。`pi-one-ui` 在原始实现之上完成了入口统一、配置存储规范化、生命周期治理、Layout Ownership 收敛、Overlay 统一调度与输入路由解耦，并持续独立演进。当前实现已完全独立于上游，不依赖也不自动同步上游分支。
 
-更详细的模块边界、事件流和 ownership 约定参见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
+更详细的模块边界、事件流与 Ownership 约定参见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
 
 ## 本地开发
 

package/extensions/app/config/panel.ts

@@ -0,0 +1,117 @@
+import type {
+  OverlayAnchor,
+  OverlayMargin,
+  SizeValue,
+} from "@earendil-works/pi-tui";
+import { configStore } from "./store.ts";
+
+/**
+ * Overlay placement for the /oneui settings panel. Mirrors the Pi
+ * `OverlayOptions` subset the panel supports; persisted under the
+ * top-level `panel` key in `pi-one-ui.json`.
+ */
+export type PanelOverlayConfig = {
+  anchor: OverlayAnchor;
+  width: SizeValue;
+  maxHeight: SizeValue;
+  margin: OverlayMargin | number;
+};
+
+/** Defaults preserve the historically hardcoded /oneui panel placement. */
+export const DEFAULT_PANEL_OVERLAY: PanelOverlayConfig = {
+  anchor: "top-center",
+  width: "85%",
+  maxHeight: "90%",
+  margin: { top: 6, right: 1, bottom: 1, left: 1 },
+};
+
+const PANEL_ANCHORS: readonly OverlayAnchor[] = [
+  "center",
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right",
+  "top-center",
+  "bottom-center",
+  "left-center",
+  "right-center",
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseAnchor(value: unknown): OverlayAnchor {
+  return PANEL_ANCHORS.some((anchor) => anchor === value)
+    ? (value as OverlayAnchor)
+    : DEFAULT_PANEL_OVERLAY.anchor;
+}
+
+/** Accepts a positive column/row count or a "N%" string within 0..100. */
+function parseSizeValue(value: unknown, fallback: SizeValue): SizeValue {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  if (typeof value === "string") {
+    const match = /^(\d+(?:\.\d+)?)%$/.exec(value.trim());
+    if (match) {
+      const percent = Number(match[1]);
+      if (percent > 0 && percent <= 100) {
+        return value.trim() as SizeValue;
+      }
+    }
+  }
+  return fallback;
+}
+
+function parseMarginEdge(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+    ? value
+    : undefined;
+}
+
+/** Accepts one non-negative integer for all edges or a per-edge object. */
+function parseMargin(value: unknown): OverlayMargin | number {
+  const fallback = DEFAULT_PANEL_OVERLAY.margin;
+  if (typeof value === "number") {
+    return parseMarginEdge(value) ?? fallback;
+  }
+  if (!isRecord(value)) {
+    return fallback;
+  }
+  const defaults = isRecord(fallback) ? (fallback as OverlayMargin) : {};
+  const margin: OverlayMargin = {};
+  for (const edge of ["top", "right", "bottom", "left"] as const) {
+    margin[edge] = parseMarginEdge(value[edge]) ?? defaults[edge];
+  }
+  return margin;
+}
+
+/**
+ * Normalizes the raw `panel` config section, replacing invalid fields with
+ * defaults so a broken entry never blocks the /oneui panel from opening.
+ */
+export function normalizePanelOverlay(input: unknown): PanelOverlayConfig {
+  const source = isRecord(input) ? input : {};
+  return {
+    anchor: parseAnchor(source.anchor),
+    width: parseSizeValue(source.width, DEFAULT_PANEL_OVERLAY.width),
+    maxHeight: parseSizeValue(
+      source.maxHeight,
+      DEFAULT_PANEL_OVERLAY.maxHeight,
+    ),
+    margin: parseMargin(source.margin),
+  };
+}
+
+/**
+ * Loads the panel overlay placement from the shared store. Read fresh on
+ * every /oneui open so JSON edits apply without `/reload`.
+ */
+export function loadPanelOverlayConfig(): PanelOverlayConfig {
+  try {
+    return normalizePanelOverlay(configStore.read().panel);
+  } catch {
+    return normalizePanelOverlay(undefined);
+  }
+}

package/extensions/app/config/renderer.ts

@@ -62,6 +62,7 @@ export type Config = {
   enableContextCommand: boolean;
   enableAgentSummary: boolean;
   enableAliases: boolean;
+  enableEffortCommand: boolean;
 };
 
 function rendererConfigFrom(record: ConfigRecord): ConfigRecord {
@@ -166,6 +167,7 @@ export const DEFAULT_CONFIG: Config = {
   enableContextCommand: true,
   enableAgentSummary: true,
   enableAliases: true,
+  enableEffortCommand: true,
 };
 
 function pickEnum<T extends string>(
@@ -296,6 +298,7 @@ export function normalizeConfig(input: unknown): Config {
     enableContextCommand: source.enableContextCommand !== false,
     enableAgentSummary: source.enableAgentSummary !== false,
     enableAliases: source.enableAliases !== false,
+    enableEffortCommand: source.enableEffortCommand !== false,
   };
 }
 
@@ -350,6 +353,7 @@ export function formatConfigStatus(source: Config = config): string {
     `context=${source.enableContextCommand ? "on" : "off"}`,
     `agentSummary=${source.enableAgentSummary ? "on" : "off"}`,
     `aliases=${source.enableAliases ? "on" : "off"}`,
+    `effort=${source.enableEffortCommand ? "on" : "off"}`,
   ].join(" · ");
 }