pi-one-ui 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-30
+
+### Added
+
+- Added a maintained English README with bidirectional language navigation.
+
+### Changed
+
+- Use `~/.pi/agent/pi-one-ui.json` as the only configuration source.
+- Persist settings with the canonical v1 `components` and `renderer` structure.
+
+### Removed
+
+- Removed automatic loading and migration of `pi-mine-ui.json`, `zentui.json`, and `claude-code-style.json`.
+- Removed legacy flat configuration fields, old style identifiers, and WorkingLine aliases.
+- Removed the legacy `enableWorkingMessage` renderer option.
+
+### Migration
+
+- Before upgrading, recreate or translate supported settings into the canonical `components` and `renderer` structure in `~/.pi/agent/pi-one-ui.json`.
+- Use `/oneui` to write settings in the canonical format, then run `/reload`.
+
+## [0.2.2] - 2026-08-29
+
+### Fixed
+
+- Reduced rendering lag when expanding settled tool groups by reusing cached child output.
+
+[Unreleased]: https://github.com/kerolt/pi-one-ui/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/kerolt/pi-one-ui/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/kerolt/pi-one-ui/compare/v0.2.1...v0.2.2

package/README.en.md

@@ -0,0 +1,256 @@
+# pi-one-ui
+
+[![npm version](https://img.shields.io/npm/v/pi-one-ui?style=flat-square)](https://www.npmjs.com/package/pi-one-ui)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522.19-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/kerolt/pi-one-ui?style=flat-square)](./LICENSE)
+
+[简体中文](./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:
+
+- the terminal shell 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.
+
+## Features
+
+### Unified interface layout
+
+`pi-one-ui` organizes the Pi interface into the following layouts:
+
+```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, and turn summaries.
+- **Editor**: input editor, completion, metadata, Accent Rail, and Minimalist styles.
+- **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.
+
+### 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 |
+| Markdown enhancement | Adds Mermaid, admonitions, URL linking, and related rendering improvements | Automatic |
+| Built-in themes | Provides CC Dark and CC Light themes | `/theme` |
+| Compatibility aliases | Optionally provides common command aliases | `/clear`, `/exit` |
+
+## Quick start
+
+### Requirements
+
+- Node.js `>=22.19.0`
+- Pi and related runtime packages `>=0.84.0`
+
+### Install from npm
+
+```bash
+pi install npm:pi-one-ui
+```
+
+### Install from GitHub
+
+```bash
+pi install git:github.com/kerolt/pi-one-ui
+```
+
+After installation, reload extensions in Pi:
+
+```text
+/reload
+```
+
+Then open the unified settings panel:
+
+```text
+/oneui
+```
+
+## Configuration
+
+The configuration file is located at:
+
+```text
+~/.pi/agent/pi-one-ui.json
+```
+
+Using the `/oneui` settings panel is recommended. The current configuration uses the v1 structure, for example:
+
+```json
+{
+  "version": 1,
+  "components": {
+    "editor": {
+      "enabled": true,
+      "style": "opencode"
+    },
+    "userMessages": {
+      "enabled": true,
+      "style": "framed"
+    },
+    "workingLine": {
+      "enabled": true
+    },
+    "footer": {
+      "style": "starship"
+    }
+  },
+  "renderer": {
+    "mode": "on",
+    "diffViewMode": "auto"
+  }
+}
+```
+
+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.
+
+## 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.
+
+| 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-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.
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed module boundaries, event flow, and ownership conventions.
+
+## Local development
+
+### Clone the repository
+
+```bash
+git clone https://github.com/kerolt/pi-one-ui.git
+cd pi-one-ui
+npm install
+```
+
+Node.js `>=22.19.0` is required. If multiple Node.js versions are installed, switch to a compatible version first.
+
+### Run in development mode
+
+Start Pi directly with the current source:
+
+```bash
+npm run pi:dev
+```
+
+This is equivalent to:
+
+```bash
+pi --no-extensions -e ./extensions/index.ts
+```
+
+You can also install the current package as a local link:
+
+```bash
+npm run pi:install-local
+```
+
+After changing the source, run the following command in Pi:
+
+```text
+/reload
+```
+
+### Development commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm install` | Install dependencies |
+| `npm run format` | Format source, tests, and configuration files |
+| `npm run format:check` | Check formatting without modifying files |
+| `npm run lint` | Run Biome checks |
+| `npm run typecheck` | Run TypeScript type checking |
+| `npm test` | Run all tests |
+| `npm run test:node` | Run Node.js test runner tests |
+| `npm run test:vitest` | Run Vitest tests |
+| `npm run pack:check` | Preview the npm package contents |
+| `npm run verify` | Run formatting, lint, type checking, and all tests |
+
+Before submitting changes, run at least:
+
+```bash
+npm run verify
+npm run pack:check
+```
+
+### Test organization
+
+Tests are grouped by domain:
+
+- `tests/context-*`: Context content, tools, diffs, thinking, and mouse interaction.
+- `tests/working-line-*`: WorkingLine and turn summaries.
+- `tests/editor-*`: Editor, completion, metadata, transfer, and Accent Rail.
+- `tests/footer-*`: Footer rendering, formatting, layout, and status.
+- `tests/services-*`: Git, runtime, project, session, and telemetry data.
+- `tests/shell-*`: Remaining layout lifecycle glue and standalone compatibility.
+
+Changes involving the TUI lifecycle should specifically cover reloads, session tree rebuilds, compaction, regular/fullscreen TUI modes, headless mode, overlays, and third-party patch ownership.
+
+## Releases
+
+User-visible changes and upgrade notes are maintained in [CHANGELOG.md](./CHANGELOG.md). Changes under development belong in `Unreleased` and are moved to a versioned section only during a release.
+
+The project uses GitHub Actions for continuous integration and npm publishing:
+
+- [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) runs complete verification for pull requests and pushes to `main`.
+- [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) publishes to npm when a `v*.*.*` tag is pushed.
+
+To publish a new version:
+
+```bash
+# Ensure main is checked out and up to date
+git switch main
+git pull --ff-only origin main
+
+# Run release checks
+npm ci
+npm run verify
+npm run pack:check
+
+# Select the SemVer increment
+npm version patch   # Backward-compatible fixes, for example 0.2.1 -> 0.2.2
+# npm version minor # New features or breaking changes while the project is on 0.x
+# npm version major # Breaking changes after a stable 1.x release
+
+# Push the release commit and tag
+git push origin main --follow-tags
+```
+
+After the tag is pushed, the publish workflow verifies that the tag matches `package.json`, runs the full verification suite again, and publishes the public package through npm Trusted Publishing with provenance. Published npm versions cannot be overwritten, so never reuse an existing version or tag.
+
+## Contributing
+
+GitHub issues and contributions are welcome. When submitting changes:
+
+1. Keep each commit focused on one primary purpose.
+2. Use a concise Conventional Commit message, for example `fix: prevent settings panel freeze after editor toggle`.
+3. Add or update tests for behavioral changes.
+4. Run `npm run verify` and `npm run pack:check` before submitting.
+
+## License
+
+This project is released under the [MIT License](./LICENSE).

package/README.md

@@ -1,133 +1,256 @@
 # pi-one-ui
 
-`pi-one-ui` 是一个统一的 Pi TUI 插件包，将 Zentui 的终端外壳能力与 Claude Code 风格的对话内容渲染合并到一个插件中。
+[![npm version](https://img.shields.io/npm/v/pi-one-ui?style=flat-square)](https://www.npmjs.com/package/pi-one-ui)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522.19-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/kerolt/pi-one-ui?style=flat-square)](./LICENSE)
 
-## 安装
+简体中文 | [English](./README.en.md)
 
-```bash
-pi install /path/to/pi-one-ui
-# 或安装远程仓库
-pi install git:github.com/<your-account>/pi-one-ui
-```
+`pi-one-ui` 是一个面向 [Pi](https://pi.dev) 的统一 TUI 扩展包。项目的初衷是希望打造一个简单美观的 TUI 界面，最初通过源码级融合，将：
+
+- [pi-zentui](https://github.com/lmilojevicc/pi-zentui)`pi-zentui` 的终端外壳能力
+- [pi-cc-extensions](https://github.com/minuque/pi-cc-extensions) 的对话内容渲染及生产力功能
+
+整合到同一个可安装、可配置的 Pi package 中，并在此基础上持续进行模块重构、职责收敛和独立优化。
+
+## 特性
 
-安装后执行 `/reload`。
+### 统一的界面布局
 
-## 统一入口
+`pi-one-ui` 将 Pi 的交互界面划分为以下布局：
 
 ```text
-/oneui
+Header → Context → WorkingLine → Editor → Footer
 ```
 
-`/oneui` 是唯一的公开管理命令。设置面板按照 TUI 的视觉 Layout 划分：
+- **Header**：启动信息、Logo 和快捷键提示。
+- **Context**：对话内容区，包含用户消息、Assistant 消息、Thinking、Tool、Diff、Markdown 和 Summary。
+- **WorkingLine**：工作状态、spinner、token/thought/elapsed 信息和回合摘要。
+- **Editor**：输入编辑器、completion、metadata、Accent Rail 和 Minimalist 样式。
+- **Footer**：目录、Git、runtime、token、cost 和扩展状态等信息。
+- **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 的统一展示                  | 自动生效          |
+| Markdown enhancement  | 支持 Mermaid、提示框和 URL 链接化等增强渲染                            | 自动生效          |
+| Built-in themes       | 提供 CC Dark 和 CC Light 主题                                          | `/theme`          |
+| Compatibility aliases | 可选提供常用命令别名                                                   | `/clear`、`/exit` |
+
+## 快速开始
+
+### 环境要求
+
+- Node.js `>=22.19.0`
+- Pi 及其相关运行时包 `>=0.84.0`
+
+### 从 npm 安装
+
+```bash
+pi install npm:pi-one-ui
+```
+
+### 从 GitHub 安装
+
+```bash
+pi install git:github.com/kerolt/pi-one-ui
+```
+
+安装完成后，在 Pi 中重新加载扩展：
 
 ```text
-Header → Context → WorkingLine → Editor → Footer → Features → Presets
+/reload
 ```
 
-其中：
+然后使用统一入口打开设置：
 
-- **Header**：启动信息、Logo、快捷键提示。
-- **Context**：对话内容区，包含 User Message、Assistant Message、Thinking、Tool、Diff、Summary 和鼠标交互。
-- **WorkingLine**：Pi 的工作状态行、spinner、token/thought/elapsed 信息。
-- **Editor**：输入编辑器、completion、metadata、Accent Rail 和 Minimalist 样式。
-- **Footer**：目录、Git、runtime、token、cost、extension status 等信息。
-- **Features**：Context Inspector、Session Reference、Subagent Autocomplete、Aliases 等行为能力。
-- **Overlay**：设置面板和 Context Inspector 等临时浮层由统一 OverlayManager 跟踪。
+```text
+/oneui
+```
 
 ## 配置
 
-配置文件：
+配置文件位于：
 
 ```text
 ~/.pi/agent/pi-one-ui.json
 ```
 
-当前仍兼容 v1 配置结构：
+推荐通过 `/oneui` 设置面板修改配置。当前配置仍使用 v1 结构，例如：
 
 ```json
 {
   "version": 1,
   "components": {
-    "editor": { "enabled": true, "style": "opencode" },
-    "userMessages": { "enabled": true, "style": "framed" },
-    "workingLine": { "enabled": true },
-    "footer": { "style": "starship" }
+    "editor": {
+      "enabled": true,
+      "style": "opencode"
+    },
+    "userMessages": {
+      "enabled": true,
+      "style": "framed"
+    },
+    "workingLine": {
+      "enabled": true
+    },
+    "footer": {
+      "style": "starship"
+    }
   },
   "renderer": {
     "mode": "on",
-    "diffViewMode": "auto",
-    "enableWorkingMessage": false
+    "diffViewMode": "auto"
   }
 }
 ```
 
-所有读写已经经过统一 ConfigStore；旧的 `zentui.json`、`claude-code-style.json` 和 `pi-mine-ui.json` 会被兼容读取并保留。`enableWorkingMessage` 仍可被旧配置读取，但统一插件不会注册第二套 working-message 实现，WorkingLine 的唯一 owner 是本插件的 WorkingLine layout。
+不同布局和渲染器的可用选项会随版本变化，建议优先使用 `/oneui` 面板进行配置。
+
+### Canonical 配置约定
 
-## 源码结构
+`pi-one-ui` 只读取和写入：
 
 ```text
-extensions/
-  index.ts                         # 唯一插件入口，创建 TuiRuntime
-  app/
-    runtime/                       # TuiRuntime、state、事件和调度
-    host/                          # Pi API 的窄化 host ports
-    config/                        # ConfigStore 与配置领域解析
-    ownership/                     # Layout ownership
-    overlay/                       # OverlayManager、InputRouter、selector
-    commands/                      # /oneui and settings panel previews
-  layouts/
-    header/                        # Header layout
-    context/                       # 原 Transcript：对话内容区
-      message/                     # User Message
-      thinking/                    # Thinking
-      renderer/                    # Tool、Diff、Markdown、Mouse
-      summary/                     # Agent summary
-    working-line/                  # WorkingLine 与 interaction summary
-    editor/                        # Editor 及其样式实现
-    footer/                        # Footer 及其布局/format/status
-  features/
-    aliases.ts
-    context-inspector/             # /context，不是 Context 对话区
-    flush-docked-bash.ts
-    legacy/                        # standalone compatibility implementation
-    session-reference/
-    subagent-autocomplete.ts
-  services/                       # Git、runtime、package、project、session 数据
-  shared/                         # ANSI、format、style、icons 等共享实现
-  tools/                          # 底层组件树、patch 和 terminal helpers
-vendor/                           # 只读上游参考快照
+~/.pi/agent/pi-one-ui.json
 ```
 
-`TuiRuntime` 是唯一 composition root，并直接装配 Layout controllers、services 和 shared lifecycle effects。standalone compatibility harness 只位于 `tests/support/`，不进入安装包。
+不会自动读取、合并或迁移其他历史配置文件，也不会解析旧版扁平字段和旧 style 名称。配置文件不存在时，运行时直接使用内置默认值；首次通过 `/oneui` 修改设置时才创建文件。所有持久化修改统一写入当前 v1 的 `components` 和 `renderer` 结构。
+
+## 上游来源与项目演进
 
-## 开发
+`pi-one-ui` 以以下两个开源项目的源码为初始基础，并对它们进行源码级融合。在此再次感谢两个上游项目及其贡献者，他们为 `pi-one-ui` 提供了最初的实现基础。
+
+| 上游项目                                                        | 融入 `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-one-ui` 提供了最初的实现基础，而本项目后续的工作重点是将这些能力收敛为一个边界清晰、可持续维护的统一产品。
+
+更详细的模块边界、事件流和 ownership 约定参见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
+
+## 本地开发
+
+### 获取源码
 
 ```bash
+git clone https://github.com/kerolt/pi-one-ui.git
+cd pi-one-ui
 npm install
-npm run typecheck
-npm test
-npm run pack:check
 ```
 
-完整检查：
+项目要求 Node.js `>=22.19.0`。如果本机安装了多个 Node.js 版本，请先切换到满足要求的版本。
+
+### 开发模式运行
+
+直接使用当前源码启动 Pi：
+
+```bash
+npm run pi:dev
+```
+
+该命令等价于：
+
+```bash
+pi --no-extensions -e ./extensions/index.ts
+```
+
+也可以将当前 package 以本地链接方式安装：
+
+```bash
+npm run pi:install-local
+```
+
+修改代码后，在 Pi 中执行：
+
+```text
+/reload
+```
+
+### 常用开发命令
+
+| 命令                   | 用途                               |
+| ---------------------- | ---------------------------------- |
+| `npm install`          | 安装依赖                           |
+| `npm run format`       | 格式化源码、测试和配置文件         |
+| `npm run format:check` | 检查格式但不修改文件               |
+| `npm run lint`         | 运行 Biome 检查                    |
+| `npm run typecheck`    | 执行 TypeScript 类型检查           |
+| `npm test`             | 运行全部测试                       |
+| `npm run test:node`    | 运行 Node.js test runner 测试      |
+| `npm run test:vitest`  | 运行 Vitest 测试                   |
+| `npm run pack:check`   | 预览 npm 实际打包内容              |
+| `npm run verify`       | 执行格式、lint、类型检查和全部测试 |
+
+提交修改前建议至少运行：
 
 ```bash
 npm run verify
+npm run pack:check
 ```
 
-测试按领域划分：
+### 测试组织
+
+测试按照功能领域划分：
 
-- `tests/context-*`：Context 内容区、Tool、Diff、Thinking 和鼠标行为。
+- `tests/context-*`：Context 内容区、Tool、Diff、Thinking 和鼠标交互。
 - `tests/working-line-*`：WorkingLine 和 turn summary。
 - `tests/editor-*`：Editor、completion、metadata、transfer 和 Accent Rail。
 - `tests/footer-*`：Footer、Footer format/layout/status。
 - `tests/services-*`：Git、runtime、project、session 和 telemetry。
-- `tests/shell-*`：standalone compatibility tests for the remaining layout lifecycle glue。
+- `tests/shell-*`：剩余布局生命周期 glue 和 standalone compatibility。
+
+涉及 TUI 生命周期的修改，应特别覆盖 reload、session tree rebuild、compact、regular/fullscreen TUI、headless mode、overlay 和第三方 patch ownership 等场景。
+
+## 发布
+
+用户可见变更和升级说明统一记录在 [CHANGELOG.md](./CHANGELOG.md)。开发中的变更先写入 `Unreleased`，正式发版时再归档到对应版本。
 
-本地启动：
+项目使用 GitHub Actions 进行持续集成和 npm 发布：
+
+- [`.github/workflows/ci.yml`](./.github/workflows/ci.yml)：在 Pull Request 和 `main` 分支提交时执行完整验证。
+- [`.github/workflows/publish.yml`](./.github/workflows/publish.yml)：推送符合 `v*.*.*` 格式的 tag 时发布 npm 包。
+
+发布新版本时：
 
 ```bash
-npm run pi:dev
+# 确认位于 main，并同步远程代码
+git switch main
+git pull --ff-only origin main
+
+# 发布前检查
+npm ci
+npm run verify
+npm run pack:check
+
+# 按 SemVer 升级版本
+npm version patch   # 向后兼容的修复，例如 0.2.1 -> 0.2.2
+# npm version minor # 0.x 阶段的新功能或破坏性变更
+# npm version major # 进入稳定 1.x 后的破坏性变更
+
+# 推送版本 commit 和 tag
+git push origin main --follow-tags
 ```
 
-上游快照保存在 `vendor/`，仅用于追踪和同步。不要直接修改 `vendor/` 或 `node_modules/`。
+推送 tag 后，发布 workflow 会校验 tag 版本与 `package.json` 版本一致，重新执行验证，并通过 npm Trusted Publishing 发布带 provenance 的公开包。已发布的 npm 版本不可覆盖，因此不要重复使用已经发布过的版本号或 tag。
+
+## 贡献
+
+欢迎通过 GitHub Issues 报告问题或提出改进建议。提交代码时建议：
+
+1. 保持每个 commit 只包含一个主要目的。
+2. 使用简洁的 Conventional Commit message，例如 `fix: prevent settings panel freeze after editor toggle`。
+3. 为行为修改补充或更新测试。
+4. 提交前运行 `npm run verify` 和 `npm run pack:check`。
+
+## 许可证
+
+本项目基于 [MIT License](./LICENSE) 发布。