kapsel-cli 0.1.0__tar.gz

kapsel_cli-0.1.0/PKG-INFO

@@ -0,0 +1,397 @@
+Metadata-Version: 2.4
+Name: kapsel-cli
+Version: 0.1.0
+Summary: 💊 跨平台自适应智能终端胶囊 (Cross-platform adaptive smart terminal capsule)
+Author-email: MrEiu <k648888@vip.qq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/MrEiu/Kapsel
+Project-URL: Repository, https://github.com/MrEiu/Kapsel
+Project-URL: Issues, https://github.com/MrEiu/Kapsel/issues
+Keywords: terminal,shell,cli,capsule,prompt,completion,i18n,carapace
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: prompt_toolkit>=3.0.40
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: shellingham>=1.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+
+# 💊 Kapsel：跨平台自适应智能终端胶囊
+
+<p align="center">
+  <b>Wrap complexity, expose simplicity. 包裹复杂，暴露极简。</b><br>
+  现代化 UI 体验的跨平台交互式终端增强包装器（CLI Wrapper）。
+</p>
+
+---
+
+## 📝 产品理念 (Philosophy)
+
+**Kapsel**（德语“胶囊”）是一款具有现代化 UI 体验的跨平台交互式终端包装器（CLI Wrapper）。
+
+它的核心理念是**“包裹复杂，暴露极简”**。Kapsel 完全接管终端输入流，**不侵入任何操作系统原生配置**（无需修改 `.bashrc`、`config.fish` 或 PowerShell Profile）。它以 **Linux 原生命令** 为主导肌肉记忆，结合**双态智能引擎**，让开发者在 Windows、macOS 和 Linux 上都能享受高度一致、极致优雅的命令行体验。
+
+---
+
+## 🚀 核心特性
+
+### 1. 核心交互：双态智能引擎 (Dual-State Engine)
+
+在同一个输入框内实现无缝、克制的双态切换：
+
+- **默认态：安静的终端增强器 (Native Mode)**
+  - **原生无感透传**：原汁原味地执行当前系统的原生命令（如 `git push`, `npm run dev`, `vim`, `python`），绝不拦截，完美兼容交互式程序与标准输入输出。
+  - **历史智能预测 (Autosuggestion)**：基于独立的本地历史数据库，在光标后方以暗灰色文本实时预测命令，按 **`→` (右方向键)** 一键采纳。
+  - **原生路径补全**：输入 `cd ` 并按下 **Tab**，自动读取当前操作系统的真实目录和文件进行智能补全。
+
+- **映射态：跨平台翻译胶囊 (Kapsel Mode)**
+  - **动态无缝切入**：输入 `kps ` 加空格瞬间进入“胶囊模式”，补全数据源即刻切换为跨平台指令集。
+  - **Linux-First 肌肉记忆**：完全采用熟悉的 Linux 基础命令作为触发词（如 `kps rm -rf`, `kps ls -la`, `kps ps`, `kps grep`）。
+  - **富文本感知菜单**：下拉菜单展示匹配的 Linux 映射指令，附带高亮中文说明，并在右侧实时预览即将执行的底层真实代码。
+  - **剥离与派发**：按下回车后，Kapsel 自动剥离 `kps ` 前缀，提取核心参数，将其翻译为当前终端的最佳原生指令并执行。
+
+### 2. 终端级精细化路由与降级 (Terminal-Level Routing)
+
+Kapsel 实现了比“操作系统级”更硬核的终端（Shell）级精细化路由与降级回退机制：
+
+- **环境深度嗅探**：启动时精准识别外层宿主是 `pwsh`, `powershell`, `cmd`, `bash`, `zsh` 还是 `fish`。
+- **多级降级匹配**：例如指令 `kps ls -la`：
+  - 检测到 `zsh`：优先执行美化版指令 `eza -la --icons`
+  - 检测到 `powershell` / `pwsh`：执行 `Get-ChildItem -Force`
+  - 检测到 `cmd`：执行 `dir /Q /A`
+  - 通用 Unix 环境：执行 `ls -la`
+- **智能参数注入 (`{{args}}`)**：输入 `kps rm -rf node_modules` 时，Kapsel 自动提取参数并无缝注入到 YAML 配置的占位符中（如 `Remove-Item -Recurse -Force node_modules`）。
+
+### 3. 独立沙箱化的用户状态 (Isolated State DB)
+
+- **历史无缝漫游**：统一将历史输入写入外部的 SQLite 数据库 `~/.kapsel/history.db`。无论昨天在 Windows CMD 还是今天在 pwsh 中，都能随时调出完整的跨平台历史记录。
+- **频次权重学习**：基于 SQLite 自动记录命令使用频次，高频映射指令在补全菜单中享有最高优先级排序。
+
+### 4. 现代美学界面 (Aesthetic UI/UX)
+
+- **区块化视觉封装**：采用现代符号连线（`╭─ ❯` 和 `╰─`），将“输入 -> 耗时执行 -> 输出结果”在终端里视觉化为一个独立、闭合的卡片区块。
+- **优雅的状态反馈**：执行结束后自动返回鲜明的状态标识（绿色的 `✔ 0` 或标红的退出码 `✘ exit 1`）以及毫秒级执行耗时（`⏱ 42ms`）。
+- **动态环境欢迎页**：启动时展示圆角边框面板，智能播报当前检测到的宿主终端、提权状态（Root / Admin / User）及配置文件加载情况。
+
+---
+
+## 📁 规范化数据沙箱设计
+
+安装运行后，Kapsel 将在用户主目录自动生成标准化的数据目录：
+
+```text
+~/.kapsel/
+├── config.yaml       # 系统级 UI 配置 (主题颜色、符号样式、动画开关等)
+├── commands.yaml     # Linux-First 自适应映射指令集 (支持团队 Git 共享)
+├── history.db        # 跨平台的独立用户历史输入与频次分析数据库 (SQLite)
+└── logs/             # Kapsel 自身的运行报错与调试日志
+```
+
+### `commands.yaml` 配置示例
+
+```yaml
+commands:
+  - alias: "rm -rf"
+    desc: "递归强制删除目录或文件"
+    mapping:
+      powershell: "Remove-Item -Recurse -Force {{args}}"
+      cmd: "rmdir /S /Q {{args}}"
+      unix: "rm -rf {{args}}"
+
+  - alias: "ls -la"
+    desc: "详细列出所有文件（含隐藏文件）"
+    mapping:
+      zsh: "eza -la --icons {{args}}"
+      powershell: "Get-ChildItem -Force {{args}}"
+      cmd: "dir /Q /A {{args}}"
+      unix: "ls -la {{args}}"
+```
+
+---
+
+## 🛠️ 安装与快速开始
+
+### 本地开发安装
+
+```bash
+git clone <repo-url> kapsel
+cd kapsel
+pip install -e .
+```
+
+### 使用方式
+
+1. **交互式全屏胶囊模式 (`kapsel`)**：
+   ```bash
+   kapsel
+   ```
+   进入 Kapsel 交互终端，即可体验双态补全、现代卡片包装和历史漫游。
+   - 输入 `help`：随时调出完整使用指南与指令速查手册。
+   - 输入 `status` 或 `info`：查看当前宿主 Shell、运行权限、数据沙箱与系统详细状态面板。
+   - 输入 `clear`：清除屏幕并重绘胶囊徽标。
+   - 输入 `exit`：无痕退出胶囊。
+
+2. **单次快速命令转换 (`kps`)**：
+   ```bash
+   kps rm -rf dist/
+   kps ls -la
+   kps ps
+   kps help
+   kps status
+   ```
+   直接在您现有的任意 Shell（PowerShell、CMD、Bash）中调用 `kps`，即刻转换并执行。
+
+---
+
+## 🛠️ 内置控制台指令
+
+| 指令 | 别名 | 功能说明 |
+| :--- | :--- | :--- |
+| `help` | `kps help`, `--help` | 显示详尽的使用指南、交互机制与常用指令速查手册 |
+| `status` | `info`, `kps status` | 查看当前宿主 Shell、运行权限、操作系统、数据沙箱与历史库统计 |
+| `config` | `kps config` | 查看系统核心配置看板、快速调节灵敏度与功能开关 |
+| `config path` | - | 打印配置文件 `~/.kapsel/config.yaml` 的完整绝对路径 |
+| `config edit` | - | 调用系统关联编辑器直接打开并编辑 `config.yaml` |
+| `config set <k> <v>` | - | 命令行快速修改某项配置（如 `config set sensitivity 0.2`） |
+| `config reload` | - | 即刻热重载最新配置文件，无需重启终端 |
+| `repo [subcmd]` | `kps repo`, `hub` | 📦 访问指令云仓库（支持 `list`, `search`, `info`, `pull`, `mappings`） |
+| `register [user]` | `kps register` | 注册胶囊用户身份，生成专属设备指纹与加密云同步秘钥 |
+| `whoami` | `user`, `kps whoami` | 查看当前设备登录的胶囊用户、绑定邮箱与云同步就绪状态 |
+| `logout` | `kps logout` | 安全退出当前用户身份并清除本地凭证 |
+| `cd` | - | 智能切换工作目录（支持 `cd ~` 家目录、`cd -` 快速返回、`cd ..` 上级目录） |
+| `clear` | `cls` | 清屏并重新绘制极简胶囊徽标 |
+| `exit` | `quit` | 安全退出 Kapsel，无痕返回当前原生 Shell |
+
+---
+
+## 📦 指令云仓库 (Hub Repository)：两层指令集与 PWSH 独立映射
+
+为了让终端开发者能像使用 `pip`、`scoop` 或 `brew` 那样轻松获取、共享和安装各类命令行工具指令集，Kapsel 内置了基于 SQLite 的指令云仓库体系 (`kapsel/hub/registry.db`)：
+
+```
+                           ┌── hub_packages (平台 -> 软件元数据)
+ Kapsel Hub (SQLite 仓库) ─┼── hub_commands (具体软件收录的丰富子命令集)
+                           └── hub_mappings (独立终端转义映射仓库，优先聚焦 pwsh)
+```
+
+### 1. 两层架构：平台 (Platform) ➜ 软件 (Software)
+- **第一层：平台环境**：如 `windows`、`universal`（跨平台通用）、`linux`。
+- **第二层：软件工具链**：
+  - 🧰 **`scoop`** (Windows 专属)：收录 `install`, `update`, `status`, `search`, `list`, `uninstall`, `bucket`, `cleanup`, `info`, `cache` 等常用指令与用例。
+  - 🌿 **`git`** (通用)：收录 `status`, `add`, `commit`, `push`, `pull`, `checkout`, `branch`, `diff`, `log`, `clone`, `init`, `stash` 等。
+  - 🐍 **`python`** (通用)：收录 `venv`, `pip-install`, `pip-freeze`, `http-server`, `run`, `pip-list`, `pip-show`。
+  - 📦 **`npm`** (通用)：收录 `install`, `run`, `dev`, `build`, `test`, `init`, `outdated`, `list`, `cache`。
+
+### 2. 独立映射仓库 (Focused on `pwsh`)
+- 独立于软件具体业务指令，专门收录 Linux 原生命令到 **PowerShell Core / Windows PowerShell** 的精准 Cmdlet 映射模板（当前收录 32+ 条核心系统转义）。
+
+### 3. 像 `pip` / `scoop` 一样使用云仓库指令
+| 指令 | 作用描述 | 类似 pip/scoop 概念 |
+| :--- | :--- | :--- |
+| **`kps repo list`** | 按平台分类展示所有可用的软件包清单 | `pip list` / `scoop bucket list` |
+| **`kps repo search <词>`** | 跨平台全局模糊搜索软件包、子命令或中文说明 | `pip search` / `scoop search` |
+| **`kps repo info <软件名>`** | 审查该软件收录的所有指令明细、语法与示例（如 `kps repo info scoop`） | `pip show` / `scoop info` |
+| **`kps repo pull <软件名>`** | **一键拉取并安装该软件指令集**至本地活跃 `commands.yaml` | **`pip install`** / **`scoop install`** |
+| **`kps repo mappings`** | 查看独立收录的面向 pwsh 的原生命令转义库 | 查看底层原生适配表 |
+| **`kps-hub`** / **`kps repo admin`** | **独立的云仓库 CRUD 运维管理工具**（增删改查软件包、指令、映射） | 仓库源管理员工具 |
+
+#### 独立云仓库运维工具 (`kps-hub`) 快速用法：
+```bash
+# 查看云仓库统计与数据库状态
+kps-hub status
+
+# 管理软件包 (增删查)
+kps-hub pkg list
+kps-hub pkg add docker -d "Docker 容器引擎" --platform universal --category container
+kps-hub pkg del docker
+
+# 管理具体软件的指令集 (增删查)
+kps-hub cmd list scoop
+kps-hub cmd add scoop bucket "scoop bucket" -d "管理扩展 Bucket 源" --example "scoop bucket add extras"
+kps-hub cmd del scoop bucket
+
+# 管理独立 pwsh 原生映射库 (增删查)
+kps-hub map list --shell pwsh
+kps-hub map add "docker-ps" "docker.exe ps" -d "Docker 进程列表" --shell pwsh
+
+# 整个仓库导出与导入
+kps-hub export -o backup.json
+kps-hub import backup.json
+```
+
+---
+
+## ☁️ 胶囊用户身份与多端云漫游体系
+
+为了在 Windows、macOS 和 Linux 之间实现**无缝的个人工作流漫游**，Kapsel 现已内置端到端加密的数字身份系统，为后续全量云端多系统同步提供基础支撑：
+
+### 1. 凭据与设备指纹
+- **存储路径**：`~/.kapsel/user.json`
+- **安全体系**：每个设备在注册时，均会基于硬件环境生成独立的 `device_id`，并签发专属的跨端加密同步秘钥（`kps_sync_...`），无需侵入系统密钥环。
+- **漫游就绪**：后续在任一台新设备（macOS / Linux / Windows）上通过您的秘钥接入，即可自动拉取并双向同步：
+  - 📂 您的自定义 Linux-First 指令映射表 (`commands.yaml`)
+  - ⚙️ 您量身定制的终端主题与交互灵敏度参数 (`config.yaml`)
+  - 🧠 跨 Shell 的历史输入库与高频频次学习权重 (`history.db`)
+
+### 2. 账号管理常用指令
+```bash
+# 1. 交互式或单行注册胶囊账号
+kps register meru --email user@example.com
+
+# 2. 查看当前登录用户信息与设备秘钥
+kps whoami
+
+# 3. 查看系统状态看板（联动显示当前用户）
+kps status
+
+# 4. 退出登录
+kps logout
+```
+
+---
+
+## ⚙️ 配置文件与右箭头灵敏交互
+
+### 1. 配置文件位置
+Kapsel 的所有个性化设置均集中在外部沙箱的 YAML 文件中：
+- **物理路径**：`~/.kapsel/config.yaml`（在 Windows 上通常为 `C:\Users\<当前用户>\.kapsel\config.yaml`）
+- 文件内部提供全中文详尽注释，涵盖：交互灵敏度、UI 主题调色板、提示行符号、终端路由降级规则及历史漫游深度。
+
+### 2. 右箭头 (`→`) 灵敏交互设计：单按 vs 长按
+为了解决传统终端“一次性填满整行无法部分复用”的痛点，Kapsel 引入了基于按键时间敏感度的多态采纳引擎：
+- **单次轻按 (Tap)**：**逐词采纳 (Word-by-word)**。例如历史命令为 `git commit -m "update" -a`，按一下输入 `git`，再按一下输入 `commit`，方便开发者精确截取历史参数并微调。
+- **长按 / 连按 (Hold)**：**一键整行采纳 (Full Accept)**。当连续击键或长按时，系统自动判定为连按意图，瞬间将剩余全部命令一键填满！
+- **可配参数**：
+  - `autosuggest_tap_mode`: 可设为 `"word"`（逐词，默认）或 `"full"`（单按直接整行）。
+  - `autosuggest_sensitivity`: 长按/连按判定敏感度阈值（单位秒，默认 `0.25`）。两次按键时间间隔在此阈值内即判定为连续长按。
+  - `consecutive_press_threshold`: 触发整行长按所需的连续击键次数（默认 `2` 次）。
+
+#### 快速调参示例
+```bash
+# 查看当前所有重要配置
+kps config
+
+# 快速打开配置文件编辑
+kps config edit
+```
+
+### 3. 数据存储目录自定义与无痕迁移 (`kps datadir`)
+Kapsel 默认将配置文件、本地 SQLite 历史库与指令仓库保存在 `~/.kapsel`。若您希望将其存放在非系统盘（如 D盘）、外部挂载盘或同步盘中，可随时一键迁移：
+- **查看当前存储状态**：
+  ```bash
+  kps datadir
+  ```
+- **迁移到自定义路径 (自动搬迁且旧目录不留)**：
+  ```bash
+  kps datadir D:\KapselData
+  ```
+  *系统会自动转移全部 SQLite 历史记录、`config.yaml` 配置文件和指令仓库，并在搬迁完毕后彻底清理旧目录，全局永久生效。*
+- **一键恢复为系统默认路径**：
+  ```bash
+  kps datadir default
+  ```
+
+### 4. 上下方向键重构：以当前输入为原点的双向流转机制 (Origin-Centered Navigation)
+为了让开发者的双手不离开方向键即可完成最核心的高频操作，Kapsel 创新性地设计了**以当前输入为原点**的上下流转交互：
+
+```
+                ▲ 向上漫游更早历史
+                │
+     ┌──────────────────────┐
+     │ 历史模式 (History)   │ ── 按【↓】往回翻看较新历史，直到回到原点
+     └──────────────────────┘
+                ▲
+    [按 ↑ 进入] │ [按 ↓ 回到原点]
+ ───────────────┼───────────────────────────  (当前正在输入的命令行 · 原点)
+    [按 ↑ 回到] │ [按 ↓ 进入]
+                ▼
+     ┌──────────────────────┐
+     │ 补全模式 (Completion)│ ── 按【↑】往回选择上一个词条，直到回到原点
+     └──────────────────────┘
+                │
+                ▼ 向下选择下一个候选词
+```
+
+- **从原点出发**：
+  - **`↑` (上方向键)**：向上进入【历史漫游模式】，调出 SQLite 历史库中的上一条输入；
+  - **`↓` (下方向键)**：向下进入【补全候选模式】，一键唤起并自动选中第一个补全词！
+- **在模式内部可自由来回切换，回到原点才能进入下一个模式**：
+  - **在历史模式中**：按 `↑` 查更早历史、按 `↓` 查较新历史；一路按 `↓` **回到原点**后，再次按 `↓` 即可无缝切换进入补全模式！
+  - **在补全模式中**：按 `↓` 选下一个词条、按 `↑` 选上一个词条；一路按 `↑` **回到原点**（恢复原始输入）后，再次按 `↑` 即可无缝切换进入历史模式！
+  - **选词采纳 vs 提交执行（Enter 回车键智能分流）**：
+    - 当通过向下键选中了某个子命令或 Flag 时，按下 **`Enter`**（或 `Tab`）会**确认采纳该词条**，自动在末尾补全空格，光标停留在末尾——**绝对不会直接执行裸命令**，方便您立刻接着敲入后续参数（如 `-m "update"` 或目录名）！
+    - 只有当没有选词时，按下 `Enter` 才会提交整行命令执行。
+  - **绝对不是死板的“只能一味上一味下”**，双手不离方向键，自由丝滑来回穿梭！
+
+---
+
+## 📋 预置常用命令一览
+
+| Linux 命令 | 功能说明 | PowerShell 映射 | CMD 映射 |
+| :--- | :--- | :--- | :--- |
+| `rm -rf` | 递归强制删除 | `Remove-Item -Recurse -Force` | `rmdir /S /Q` |
+| `rm` | 删除文件 | `Remove-Item` | `del /Q` |
+| `ls -la` / `ll` | 详细列出文件 | `Get-ChildItem -Force` | `dir /Q /A` |
+| `cat` | 查看文件内容 | `Get-Content` | `type` |
+| `touch` | 创建空文件 | `New-Item -ItemType File -Force` | `type nul >>` |
+| `cp -r` | 递归复制 | `Copy-Item -Recurse -Force` | `xcopy /E /I /Y` |
+| `mv` | 移动/重命名 | `Move-Item -Force` | `move /Y` |
+| `mkdir -p` | 递归建目录 | `New-Item -ItemType Directory -Force` | `mkdir` |
+| `ps` | 查看进程列表 | `Get-Process` | `tasklist` |
+| `kill -9` | 强制终止进程 | `Stop-Process -Force -Id` | `taskkill /F /PID` |
+| `grep` | 文本模式匹配 | `Select-String` | `findstr` |
+| `find` | 递归查找文件 | `Get-ChildItem -Recurse -Filter` | `dir /S /B` |
+| `which` | 查找程序路径 | `Get-Command` | `where` |
+| `df -h` | 磁盘空间统计 | `Get-PSDrive -PSProvider FileSystem` | `wmic logicaldisk ...` |
+| `clear` | 清屏 | `Clear-Host` | `cls` |
+| `ifconfig` / `ip a` | 查看网卡信息 | `Get-NetIPAddress` | `ipconfig /all` |
+| `env` | 环境变量列表 | `Get-ChildItem env:` | `set` |
+| `head` | 查看前 10 行 | `Get-Content -Head 10` | `powershell ...` |
+| `tail` | 查看后 10 行 | `Get-Content -Tail 10` | `powershell ...` |
+
+---
+
+## 🔮 未来规划 (Roadmap)
+
+- **非侵入式交互看板 (Context Stream)**：
+  - 在后续版本中，计划将交互底栏演进为可插拔关键信息看板：
+    - **Git 状态流**：实时反映未暂存修改、未推送 Commit 计数
+    - **环境上下文**：Python 虚拟环境 (`venv`/`conda`)、Node 运行时版本自动感知
+    - **后台与性能监控**：耗时后台任务执行进度、系统资源告警
+    - **AI 智能建议**：基于历史错误码的自适应修复提示
+- **配置云漫游与团队共享**：支持通过用户数字凭据一键跨设备同步指令集与历史漫游。
+- **自定义指令热重载**：在外部修改 `~/.kapsel/commands.yaml` 时无感知热重载。
+- 📖 **深度技术白皮书**：详细架构与演进方案已整理至 [《Kapsel 指令存储与映射架构分析与全方位优化方案》](docs/command_storage_and_mapping_architecture.md)。
+- 🛠️ **开发架构规范 (DEVELOPMENT.md)**：开发守则与核心铁律已写入 [《Kapsel 架构设计与开发规范》](DEVELOPMENT.md)（坚决杜绝代码硬编码，杜绝配置文件堆叠，坚持云仓库集中、客户端同步、本地高速读取）。
+- 📡 **云端与本地通信架构提案**：详见 [《Kapsel 本地与云端通信方案调研与架构选型报告》](docs/local_cloud_communication_proposals.md)（深度对比 REST API、Git CDN、SQLite Changeset、gRPC 与混合架构五大方案）。
+
+## 🙏 特别致谢 (Acknowledgments)
+
+- **Fig / Amazon Q (`withfig/autocomplete`)**：
+  > *“Fig 是我制作完功能后意外发现的；之后全面兼容了该仓库，感谢各位先贤的贡献。”*  
+  Kapsel 深度兼容并吸纳了其优秀的 `Fig.Spec` 树形补全规范，使开发者在拥有强大的跨平台原生转义映射的同时，享受全球顶级的终端自动补全体验。
+
+---
+
+## 📄 License
+
+MIT License.
+