@zhizuqiu/cubectl 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,139 @@
+# Cubectl
+
+🚀 **Cubectl** 是一个基于 AI 驱动的 Kubernetes 运维助手终端工具，使用 [Ink](https://github.com/vadimdemedes/ink) 构建。
+
+用户可以通过自然语言与 Kubernetes 集群进行交互，无需记忆复杂的 `kubectl` 命令。它支持自动执行工具调用来查询资源，并提供实时的流式 AI 响应。
+
+## 核心特性
+
+- 🤖 **自然语言交互**：直接询问 "有哪些 pods 正在运行？" 或 "帮我查一下 default 命名空间的 service"。
+- 📡 **流式响应**：实时展示 AI 的思考过程和输出结果，类似于 ChatGPT 的打字机体验。
+- 🔧 **动态资源发现**：基于 `unstructured` 对象的动态 Kubernetes 客户端，支持几乎所有 K8s 资源类型（Pods, Deployments, Services, CRDs 等）。
+- 💻 **终端原生 UI**：利用 React 和 Ink 构建，支持原生终端滚动、彩色高亮和加载动画。
+- 🌏 **中英双语**：内置 i18n 支持，根据系统自动适配或手动配置。
+- 🔍 **一键摘要**：快速获取命名空间的资源概览统计。
+
+## 项目结构
+
+这是一个使用 npm workspaces 管理的 monorepo：
+
+```
+cubectl/
+├── packages/
+│   ├── core/          # 核心库：包含 AI Agent 逻辑、动态 K8s 客户端和工具定义
+│   └── cli/           # CLI 应用：Ink UI 组件和命令行入口
+├── scripts/           # 构建和辅助脚本
+├── .env.example       # 环境变量模板
+└── package.json       # 根工作区配置
+```
+
+## 快速开始
+
+### 前提条件
+
+- **Node.js**: >= 20.0.0 (必须，因为依赖使用了正则表达式 `v` 标志)
+- **npm**: >= 10.0.0
+- **Kubernetes**: 具有有效的 `~/.kube/config` 配置
+
+### 安装与构建
+
+```bash
+# 克隆并安装依赖
+npm install
+
+# 配置环境变量 (详见下文 环境变量 章节)
+cp .env.example .env
+
+# 构建项目
+npm run build
+```
+
+## 环境变量配置
+
+在项目根目录下创建一个 `.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` 并全局运行：
+
+```bash
+# 安装
+npm install -g @zhizuqiu/cubectl
+
+# 直接使用
+cubectl "列出 pods"
+```
+
+### 源码安装（开发调试）
+
+如果您想在本地开发或调试：
+
+```bash
+# 1. 克隆并安装依赖
+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 -w @zhizuqiu/cubectl --access public
+```
+
+### 运行
+
+```bash
+# 启动交互式终端
+npm start
+
+# 直接执行查询
+npm start "显示所有运行中的 pods"
+
+# 启用调试模式
+npm start -- --debug
+```
+
+## 命令行参数
+
+- `-d, --debug`: 启用调试模式
+- `-c, --context <context>`: 指定 Kubernetes 上下文
+- `-n, --namespace <namespace>`: 指定命名空间 (默认为 default)
+- `-ae, --auto-execute`: 开启自动执行模式 (实验性)
+- `-h, --help`: 显示帮助信息
+- `--version`: 显示版本号
+
+## 开发指南
+
+详见 **[DEVELOPER.md](./DEVELOPER.md)**。
+
+## 许可证
+
+MIT