@zhizuqiu/cubectl 0.1.3 → 1.0.1

package/README.md

@@ -1,139 +1,62 @@
-# Cubectl
-
-🚀 **Cubectl** 是一个基于 AI 驱动的 Kubernetes 运维助手终端工具，使用 [Ink](https://github.com/vadimdemedes/ink) 构建。
-
-用户可以通过自然语言与 Kubernetes 集群进行交互，无需记忆复杂的 `kubectl` 命令。它支持自动执行工具调用来查询资源，并提供实时的流式 AI 响应。
+English | [中文](./docs/manual/README.zh-CN.md)
 
-## 核心特性
+# Cubectl
 
-- 🤖 **自然语言交互**：直接询问 "有哪些 pods 正在运行？" 或 "帮我查一下 default 命名空间的 service"。
-- 📡 **流式响应**：实时展示 AI 的思考过程和输出结果，类似于 ChatGPT 的打字机体验。
-- 🔧 **动态资源发现**：基于 `unstructured` 对象的动态 Kubernetes 客户端，支持几乎所有 K8s 资源类型（Pods, Deployments, Services, CRDs 等）。
-- 💻 **终端原生 UI**：利用 React 和 Ink 构建，支持原生终端滚动、彩色高亮和加载动画。
-- 🌏 **中英双语**：内置 i18n 支持，根据系统自动适配或手动配置。
-- 🔍 **一键摘要**：快速获取命名空间的资源概览统计。
+🚀 **Cubectl** is a state-of-the-art AI-powered Kubernetes operations assistant terminal tool built with [Ink](https://github.com/vadimdemedes/ink) and [LangChain](https://github.com/langchain-ai/langchainjs).
 
-## 项目结构
+Interact with your Kubernetes clusters using natural language. No more memorizing complex `kubectl` flags—just ask and let the AI handle the heavy lifting with full Human-in-the-Loop safety.
 
-这是一个使用 npm workspaces 管理的 monorepo：
+## ✨ Key Features
 
-```
-cubectl/
-├── packages/
-│   ├── core/          # 核心库：包含 AI Agent 逻辑、动态 K8s 客户端和工具定义
-│   └── cli/           # CLI 应用：Ink UI 组件和命令行入口
-├── scripts/           # 构建和辅助脚本
-├── .env.example       # 环境变量模板
-└── package.json       # 根工作区配置
-```
+- 🤖 **Natural Language Intelligence**: Query resources ("How many nodes are ready?") or modify them ("Scale my deployment to 3 replicas") with ease.
+- 📡 **Robust Streaming UI**: Experience real-time AI reasoning and output with a premium, flick-free terminal interface.
+- 🛡️ **Human-in-the-Loop (HITL)**: Safety first. Sensitive operations (create, patch, delete) require explicit user approval.
+- ⚡ **Autonomous Mode**: Switch to "Auto-execute" with `Ctrl+A` for the AI to perform operations without interruptions (best for trusted environments).
+- 🧩 **Deep Type Safety**: Built with strict TypeScript and aligned with official LangChain/LangGraph schemas for maximum reliability.
+- ⌨️ **Input Stability**: Custom keyboard parser ensures no character loss, even during high-frequency streaming.
+- 🔍 **Dynamic Resource Discovery**: Supports standard resources and CRDs via dynamic Kubernetes client resolution.
 
-## 快速开始
+## 🚀 Quick Start
 
-### 前提条件
+### Prerequisites
 
-- **Node.js**: >= 20.0.0 (必须，因为依赖使用了正则表达式 `v` 标志)
-- **npm**: >= 10.0.0
-- **Kubernetes**: 具有有效的 `~/.kube/config` 配置
+- **Node.js**: >= 20.0.0
+- **Kubernetes**: A valid `~/.kube/config`
 
-### 安装与构建
+### Global Installation
 
 ```bash
-# 克隆并安装依赖
-npm install
-
-# 配置环境变量 (详见下文 环境变量 章节)
-cp .env.example .env
-
-# 构建项目
-npm run build
+npm install -g @zhizuqiu/cubectl@latest
+cubectl
 ```
 
-## 环境变量配置
-
-在项目根目录下创建一个 `.env` 文件，或参考 `.env.example` 进行配置。
-
-| 变量名 | 必填 | 描述 | 默认值 |
-| :--- | :--- | :--- | :--- |
-| `OPENAI_API_KEY` | 是 | 您的 AI 模型 API Key | - |
-| `OPENAI_API_MODEL` | 否 | 使用的模型名称 | `gpt-4o` |
-| `OPENAI_BASE_URL` | 否 | API 请求的基础 URL| `https://api.openai.com/v1` |
-| `KUBECONFIG` | 否 | Kubernetes 配置文件路径 | `~/.kube/config` |
-
-> [!TIP]
-> 如果您使用的是非 OpenAI 的兼容接口（如通义千问、DeepSeek 等），请务必正确设置 `OPENAI_BASE_URL`。
-
-### NPM 全局安装 (推荐)
-
-您可以直接从 NPM 仓库安装 `cubectl` 并全局运行：
+### Local Development
 
 ```bash
-# 安装
-npm install -g @zhizuqiu/cubectl
-
-# 直接使用
-cubectl "列出 pods"
-```
-
-### 源码安装（开发调试）
-
-如果您想在本地开发或调试：
-
-```bash
-# 1. 克隆并安装依赖
+git clone https://github.com/zhizuqiu/cubectl.git
+cd cubectl/cubectl
 npm install
-
-# 2. 构建项目
 npm run build
-
-# 3. 链接到全局
-cd packages/cli
-sudo npm link
-
-# 现在可以使用 cubectl 命令了
-cubectl "列出 pods"
-```
-
-### 如何发布到 NPM
-
-如果您是项目维护者，可以按照以下步骤发布新版本：
-
-```bash
-# 1. 确保已登录 npm
-npm login
-
-# 2. 构建所有 workspace
-npm run build
-
-# 3. 发布 cli 包
-npm publish --access public
-```
-
-### 运行
-
-```bash
-# 启动交互式终端
 npm start
-
-# 直接执行查询
-npm start "显示所有运行中的 pods"
-
-# 启用调试模式
-npm start -- --debug
 ```
 
-## 命令行参数
+## ⚙️ Configuration
+
+Cubectl supports environment variables via `.env` files (Project root or `~/.cubectl/.env`).
 
-- `-d, --debug`: 启用调试模式
-- `-c, --context <context>`: 指定 Kubernetes 上下文
-- `-n, --namespace <namespace>`: 指定命名空间 (默认为 default)
-- `-ae, --auto-execute`: 开启自动执行模式 (实验性)
-- `-h, --help`: 显示帮助信息
-- `--version`: 显示版本号
+| Variable           | Required | Description                         | Default                     |
+| :----------------- | :------- | :---------------------------------- | :-------------------------- |
+| `OPENAI_API_KEY`   | **Yes**  | AI model API Key                    | -                           |
+| `OPENAI_API_MODEL` | No       | Model name (e.g., qwen-max, gpt-4o) | `gpt-4o`                    |
+| `OPENAI_BASE_URL`  | No       | Custom provider endpoint            | `https://api.openai.com/v1` |
 
-## 开发指南
+## 🕹️ Controls
 
-详见 **[DEVELOPER.md](./DEVELOPER.md)**。
+- **Enter**: Send message
+- **Ctrl+A**: Toggle Autonomous Mode (Auto-execute)
+- **Arrow Up/Down**: Command history
+- **Ctrl+C**: Exit
 
-## 许可证
+## 📄 License
 
-MIT
+MIT © [zhizuqiu](https://github.com/zhizuqiu)