kubectl-qyai 是一个面向 Kubernetes 与 Linux 运维 的智能命令行助手：把自然语言需求转成可执行的命令（kubectl / bash），并在执行前做 风险分级 + 二次确认 + 审计/会话记录。

本项目基于开源项目 kubectl-ai 进行二次开发，重点增强：

• 运维安全：read/change/destructive 分层，可配置策略（提示/阻断）
• 多种运行方式：单次（预览/执行）、交互（terminal/tui）、Web UI、HTTP agent-serve、MCP tools server
• 默认中文提示，可切换英文
• 会话与审计：便于复盘与追责

• 安装
• 三分钟上手
• 使用方式
  • 单次：预览 / 执行
  • 交互：terminal / tui（推荐）
  • Web UI（浏览器界面）
  • HTTP：agent-serve（远程触发本机 Agent）
  • MCP：tools server（给外部 Agent/平台用）
• 模型与提供方
• 配置与文件
  • config.yaml（模型与安全策略）
  • 凭据与 .env 加载顺序
  • 会话与审计
  • 日志
• 容器与开发

curl -fsSL https://cnb.cool/qianyios/kubectl-qyai/-/git/raw/main/install.sh | bash

指定版本：

curl -fsSL https://cnb.cool/qianyios/kubectl-qyai/-/git/raw/main/install.sh | QYAI_VERSION=v1.1.2 bash

安装完成后的目录结构：

• /usr/local/kubectl-qyai/bin/：kubectl-qyai、kubeqy
• /usr/local/kubectl-qyai/conf/：config.yaml、config.example.yaml、.env、.env.example
• /usr/local/kubectl-qyai/scripts/：随包脚本（例如 start-agent-serve.sh）
• /usr/local/kubectl-qyai/log/：默认日志目录（kubectl-qyai.log）

install.sh 会把命令软链到 /usr/local/bin/，确保 PATH 可找到。

go build -o ./bin/kubectl-qyai ./cmd/kubectl-qyai
ln -sf ./bin/kubectl-qyai ./bin/kubeqy

1. 选择运行环境（影响工具执行方式与默认提示词）：

export KUBEQY_PATH=linux
# export KUBEQY_PATH=kubernetes

2. 准备配置文件（模型列表 + 默认模型 + 安全策略）：

• 复制 config.example.yaml 为 config.yaml 并修改，或直接放到默认路径：
  • /usr/local/kubectl-qyai/conf/config.yaml

3. 配置至少一个模型凭据（建议写到 .env）：

• 参考 .env.example（模板）
• 你至少需要设置一个 key（例如 DEEPSEEK_API_KEY / QWEN_API_KEY / OPENAI_API_KEY 等）

4. 开跑：

kubeqy

• 预览（默认）：

kubeqy -p "获取所有 Pod"

• 执行（会询问确认）：

kubeqy -p "获取所有 Pod" -e

kubeqy
# 或
kubectl-qyai --ui-type=terminal
kubectl-qyai --ui-type=tui

交互模式要点：

• 默认对齐上游风格：terminal/tui + agent 多轮迭代 + 工具调用
• 常用内置命令：
  • help / ?
  • tools（可用工具）
  • models / model（模型列表 / 当前模型）
  • sessions / resume-session <id> / new-session
  • clear / reset
  • exit / quit
• Ctrl+C：两段式——先取消当前执行，再按一次退出

语言：默认中文，可切换英文。

• 切换为英文（环境变量方式）：

export KUBECTL_QYAI_LANG=en

交互模式里也可以用内置命令切换：输入 help 查看 lang 用法（通过序号选择）。

kubectl-qyai ui --listen 127.0.0.1:18082

说明：Web UI 是本机 HTTP + SSE，用于浏览器里交互与会话管理。

适用场景：A 机器有 kubeconfig/网络/权限，B 机器只想“远程发 prompt 拿结果”。

• 直接启动：

kubectl-qyai agent-serve --runtime linux --listen 127.0.0.1:18081

• 启用 token 鉴权（推荐用于局域网/跨机器调用）：

kubectl-qyai agent-serve --runtime linux --listen 0.0.0.0:18081 --token "your-strong-token"

• 使用随包脚本（自动识别本机 IP，并拼成 <ip>:<port>）：

scripts/start-agent-serve.sh

相关环境变量（优先级：系统环境变量 > .env）：

• KUBEQY_PATH：运行环境（linux / kubernetes）
• KUBECTL_QYAI_AGENT_SERVE_PORT：端口（默认 18081）
• KUBECTL_QYAI_AGENT_SERVE_TOKEN：可选鉴权 token（为空=不开启鉴权）

HTTP 接口：

• GET /healthz
• POST /agent/run（可选：Authorization: Bearer <token>）

远程调用示例（curl）：

• 健康检查：

curl -fsSL http://127.0.0.1:18081/healthz

• 触发一次 agent 运行（无 token）：

curl -sS http://127.0.0.1:18081/agent/run \
  -H "Content-Type: application/json" \
  -d '{"prompt":"列出所有 namespace","max_iterations":5}'

• 跨机器调用（有 token，B 机器请求 A 机器）：

curl -sS http://<A机器IP>:18081/agent/run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"查看 kube-system 命名空间所有 Pod","model":"","max_iterations":10}'

说明：请求体支持字段：prompt（必填）、model（可选）、max_iterations（可选）。

MCP server 只提供工具能力（kubectl/bash/...），不替调用方托管模型与密钥。

• stdio（本机/父进程拉起）：

kubectl-qyai mcp --mode stdio --runtime linux

• streamable-http（远端暴露，endpoint 默认 /mcp）：

kubectl-qyai mcp --mode streamable-http --http-port 8080 --runtime linux

模型通过 config.yaml 的 models: 配置，按 priority 选择；默认使用 default_model。

支持的 type（总览，完整变量清单见 .env.example）：

type	典型必需环境变量	备注
qwen	QWEN_API_KEY（或 DASHSCOPE_API_KEY）	DashScope compatible-mode
deepseek	DEEPSEEK_API_KEY	OpenAI-compatible
ernie	ERNIE_API_KEY + ERNIE_SECRET_KEY	百度千帆
spark	SPARK_APP_ID + SPARK_API_KEY + SPARK_API_SECRET	讯飞星火
hunyuan	TENCENT_SECRET_ID + TENCENT_SECRET_KEY	腾讯混元
local	（可选）LOCAL_API_KEY	本地 OpenAI 兼容网关
heuristic	无	离线兜底（建议保留）

type	典型必需环境变量	备注
openai	OPENAI_API_KEY	OpenAI 官方或代理
openai-compatible	通常 OPENAI_API_KEY 或网关 key	推荐配 LLM_BASE_URL 明确网关
azopenai	AZURE_OPENAI_BASE_URL + AZURE_OPENAI_API_KEY	Azure OpenAI
gemini	GEMINI_API_KEY	Google AI Studio
vertexai	GOOGLE_CLOUD_PROJECT（及 location）	Vertex AI
ollama	无	本机 Ollama（默认 http://127.0.0.1:11434）
llamacpp	无	llama.cpp server
grok	GROK_API_KEY	xAI
bedrock	AWS 默认凭据 + region	AWS Bedrock

建议：当你同时配置了多个“兼容网关”的 key 时，在 config.yaml 里给对应模型显式设置 params.base_url，避免歧义。

默认读取路径（可用 --config 或 KUBECTL_QYAI_CONFIG 覆盖）：

• /usr/local/kubectl-qyai/conf/config.yaml
• 若不存在：回退 /usr/local/kubectl-qyai/conf/config.example.yaml

核心字段：

• models[]：模型列表（name/type/priority/enabled/params）
• default_model：默认模型（对应 models[].name）
• safety：安全策略（read/change/destructive 分层，支持自定义规则）

示例与完整注释请直接看：config.example.yaml。

优先级：环境变量 > ~/.config/kubectl-qyai/credentials.yaml。

.env 仅用于“补齐未设置的环境变量”（不覆盖你已经 export 的变量），加载顺序：

1. KUBECTL_QYAI_DOTENV 指定路径
2. 当前目录向上查找 .env
3. ~/.config/kubectl-qyai/.env
4. /usr/local/kubectl-qyai/conf/.env

模板文件：/usr/local/kubectl-qyai/conf/.env.example（或仓库根 .env.example）。

• 会话（默认启用，可 --no-session 关闭）：~/.kubectl-qyai/sessions/<id>.jsonl
• 审计（默认启用，可 --no-audit 关闭）：~/.kubectl-qyai/audit/audit-YYYYMMDD.jsonl

• 默认：优先写 /usr/local/kubectl-qyai/log/kubectl-qyai.log（目录存在时）
• 若无权限/目录不存在：回退写入系统临时目录

可选环境变量：

• KUBECTL_QYAI_LOG_DIR：自定义日志目录（会写入 kubectl-qyai.log）
• KUBECTL_QYAI_QUIET=1：关闭所有日志写入

• 容器运行与 kubeconfig 挂载方式见 CONTAINER.md
• 贡献指南见 contributing.md
• 测试：go test ./...