@volc-emr/emr-cli 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 volc-emr-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+# volc-emr-agent
+
+> 一个 **可控、可审计、可 dry-run** 的 Volcengine EMR CLI Agent。
+>
+> Tool-first · Plan → Execute · LLM Planner（可选）· 真实 OpenAPI 调用 · 本地凭证 / 偏好记忆。
+
+你用一句自然语言描述任务（例如"列出所有运行中的集群"、"清理一周前已关停的集群"、"帮我建一个 3.7.0 的 Hadoop 集群"），Agent 会：
+
+1. 由 LLM 生成一份结构化 `Plan`
+2. 高风险步骤前弹确认（或 `-y` 跳过）
+3. 交由 Executor 依次调用 Tool
+4. Tool 用 Zod 校验 LLM 输入 → 调用真实 EMR OpenAPI → 把结果写回 stdout
+5. 创建集群这类复合 Tool，会**再次**交互式向你追问缺失字段并回填常用默认值
+
+---
+
+## 已对接的 EMR OpenAPI（Version=2023-08-15）
+
+| Tool | OpenAPI Action | 风险级别 | 说明 |
+|---|---|---|---|
+| `listClusters` | [ListClusters](https://www.volcengine.com/docs/6491/1208305) | low | 支持全字段过滤 / 分页 / 中文状态别名归一化 |
+| `findClustersToCleanup` | ListClusters | low | 组合查询：超过 N 天 + 处于 SHUTDOWN 类状态 |
+| `deleteCluster` | [ReleaseCluster](https://www.volcengine.com/docs/6491/1208304) | **high** | 自动识别归档 / 已释放 / 不存在 → 幂等跳过而非中断 |
+| `createCluster` | [CreateCluster](https://www.volcengine.com/docs/6491/1208307) | **high** | 交互式补全 13 类必填字段、PRE/POST 计费分支、节点组向导 |
+
+---
+
+## 安装
+
+```bash
+# 通过 npm 全局安装（推荐）
+npm install -g @volc-emr/emr-cli@beta
+
+# 验证（CLI 命令名仍是 volc-emr-agent）
+volc-emr-agent --help
+```
+
+或者本地开发模式：
+
+```bash
+git clone <repo>
+cd console-cli
+npm install
+npm run build
+npm link        # 注册 `volc-emr-agent` 到 PATH
+```
+
+**环境要求**：Node.js ≥ 18
+
+---
+
+## 快速上手（三步）
+
+```bash
+# 1) 初始化：填 AK/SK、地域，可选一起填 LLM
+volc-emr-agent init
+
+# 2) 跑第一条命令（只打印 Plan，不执行）
+volc-emr-agent run "列出所有运行中的集群" --dry-run
+
+# 3) 真正执行
+volc-emr-agent run "列出所有运行中的集群"
+```
+
+---
+
+## 凭证与配置
+
+优先级统一为：**CLI 参数 > 环境变量 > 本地配置文件**。
+
+### 本地配置文件位置
+
+| 文件 | 内容 | 权限 |
+|---|---|---|
+| `~/.volc-emr/config.json` | Volcengine AK/SK/Region + LLM endpoint/apiKey/model | `0600` |
+| `~/.volc-emr/create-cluster-memory.json` | 创建集群向导的常用偏好（VPC/子网/可用区/机型等） | `0600` |
+
+可通过 `VOLC_EMR_CONFIG_DIR` 环境变量整体改位置（测试 / 多环境友好）。
+
+### 写配置
+
+```bash
+# 交互式向导（支持同时配 LLM）
+volc-emr-agent init
+
+# 已有配置？加 --force 跳过确认
+volc-emr-agent init --force
+
+# 非交互（CI 友好）
+volc-emr-agent init \
+  --access-key "$VOLC_ACCESSKEY" \
+  --secret-key "$VOLC_SECRETKEY" \
+  --region cn-beijing
+
+# 单独写凭证
+volc-emr-agent config set-credentials \
+  --access-key xxx --secret-key yyy --region cn-beijing
+
+# 单独写 LLM
+volc-emr-agent config set-llm \
+  --endpoint https://ark.cn-beijing.volces.com/api/v3/chat/completions \
+  --api-key ark-xxx \
+  --model doubao-seed-character-251128
+```
+
+### 环境变量
+
+```bash
+export VOLC_ACCESSKEY=xxx
+export VOLC_SECRETKEY=yyy
+export VOLC_REGION=cn-beijing
+
+# LLM（可选；未配置时 Planner 会直接报错，不做 rule-based 兜底）
+export VOLC_LLM_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/chat/completions
+export VOLC_LLM_API_KEY=ark-xxx
+export VOLC_LLM_MODEL=doubao-seed-character-251128
+```
+
+### 查看 / 重定向
+
+```bash
+# 查看已保存的本地配置（secrets 自动脱敏）
+volc-emr-agent config show
+
+# 改用自定义目录
+VOLC_EMR_CONFIG_DIR=/tmp/volc-test volc-emr-agent init
+```
+
+---
+
+## 运行示例
+
+### 列出集群
+
+```bash
+volc-emr-agent run "列出所有运行中的集群"
+volc-emr-agent run "列出 cn-beijing 最近创建的 10 个 Hadoop 集群"
+```
+
+### 清理老集群
+
+```bash
+# 看 Plan、不执行
+volc-emr-agent run "清理一周前已关停的集群" --dry-run
+
+# 批量执行（自动确认所有 high-risk 步骤）
+volc-emr-agent run "清理一周前已关停的集群" -y
+
+# 自定义天数
+volc-emr-agent run "清理 14 天前已关停的集群"
+```
+
+> 已被 EMR 归档（`marked archived`）的集群会被自动识别并**跳过**，不会让整个清理流程中断。
+
+### 创建集群（交互式向导）
+
+```bash
+volc-emr-agent run "帮我创建一个 3.7.0 的 Hadoop 集群"
+```
+
+LLM 会先从你的描述里预填能猜到的字段（`ClusterType=Hadoop, ReleaseVersion=3.7.0`），Tool 接着启动向导：
+
+```
+=== 创建 EMR 集群：补全配置 ===
+(已加载上次记忆，路径: /Users/you/.volc-emr/create-cluster-memory.json)
+
+集群类型 (可选: Hadoop / Presto / ...) [Hadoop]: ⏎
+集群版本 (ReleaseVersion) [3.7.0]: ⏎
+集群名称 [OpenApiHadoop3.7.0-a7x2m]: ⏎
+付费类型 (可选: POST / PRE) [POST]: ⏎
+VpcId (如 vpc-xxx) [vpc-abc123]: ⏎          ← 来自上次记忆
+SecurityGroupId (如 sg-xxx) [sg-def456]: ⏎  ← 来自上次记忆
+可用区 ZoneId [cn-beijing-b]: ⏎
+
+-- 节点组配置 (共 2 组) --
+[节点组 1]
+节点组类型 (可选: MASTER / CORE / TASK / GATEWAY) [MASTER]: ⏎
+  节点数 [3]: ⏎
+  SubnetIds (逗号分隔) [subnet-xyz]: ⏎
+  EcsInstanceTypes [ecs.g3i.2xlarge]: ⏎
+...
+
+=== 即将创建集群，配置如下 ===
+{ ...完整 JSON... }
+确认使用以上配置创建集群? (y/n): y
+
+(已更新常用默认值记忆: /Users/you/.volc-emr/create-cluster-memory.json)
+✓ 集群创建成功: ClusterId=emr-xxx, OperationId=op-xxx
+```
+
+**特性**：
+
+- **记忆**：用户确认后立刻写 `create-cluster-memory.json`。即使 OpenAPI 随后返回错误，下次依然能复用你填过的网络/节点偏好，不用再填一遍
+- **中文状态 / 大小写自动归一化**：LLM 写成 "已关停" / "Running" 都能被翻译成官方枚举
+- **MASTER + CORE 自动补齐**：Hadoop 类集群强制至少两个节点组
+- **ChargeType=PRE 自动展开包年包月子向导**（周期 / 自动续费）
+
+---
+
+## 命令总览
+
+| 命令 | 作用 |
+|---|---|
+| `volc-emr-agent init [--force]` | 交互式写入 AK/SK、可选一起配 LLM |
+| `volc-emr-agent config set-credentials --access-key ... --secret-key ...` | 单独更新凭证 |
+| `volc-emr-agent config set-llm --endpoint ... [--api-key ...] [--model ...]` | 单独更新 LLM |
+| `volc-emr-agent config show` | 查看本地配置（脱敏） |
+| `volc-emr-agent run <task> [--dry-run] [-y] [--region ...]` | 执行一条自然语言任务 |
+
+运行选项：
+
+- `--dry-run`：只打印 Plan，不调用任何 OpenAPI
+- `-y, --yes`：对 `riskLevel: "high"` 的 Tool 自动确认
+- `--region <region>`：临时覆盖当前会话的区域（不写配置）
+
+---
+
+## 目录结构
+
+```
+src/
+├── index.ts                      # CLI 入口（commander）
+├── agent/
+│   ├── agent.ts                  # 对外 Agent.run(task, options)
+│   ├── planner.ts                # LLM-only Planner，无 LLM 时直接报错
+│   ├── llmPlanner.ts             # 把 Zod 输入翻成 JSON Schema 喂给 LLM
+│   ├── executor.ts               # 依次执行 Plan，触发高风险确认
+│   └── types.ts
+├── services/
+│   ├── volcApi.ts                # @volcengine/openapi 签名 + 错误解析
+│   └── emrApi.ts                 # listClusters / releaseCluster / createCluster ...
+├── tools/
+│   ├── base.ts                   # Tool 定义 (name/description/input/riskLevel/execute)
+│   ├── registry.ts               # 聚合所有业务 Tool + API
+│   └── emr/
+│       ├── index.ts
+│       ├── listClusters.ts
+│       ├── findClustersToCleanup.ts
+│       ├── deleteCluster.ts      # → ReleaseCluster
+│       └── createCluster.ts      # 交互式向导 + 记忆
+├── runtime/
+│   ├── config.ts                 # AK/SK + LLM 持久化
+│   ├── createClusterMemory.ts    # 创建集群专用的偏好记忆（独立文件）
+│   ├── confirm.ts                # TTY / pipe 双模安全的 prompt
+│   ├── llm.ts                    # OpenAI-compatible Chat Completions 客户端
+│   ├── memory.ts                 # 进程内简易 KV
+│   └── logger.ts
+└── utils/prompt.ts
+```
+
+---
+
+## 关键设计
+
+### 1. Tool-first
+
+所有业务能力都是 Tool（`name / description / input (Zod) / riskLevel / execute`）。LLM 看到的只有 Tool 目录（由 `zod-to-json-schema` 自动生成），**不能直接执行副作用**。
+
+### 2. Plan → Execute 分离
+
+```
+用户自然语言
+   ↓
+Planner（LLM, Zod 校验）→ PlanStep[]
+   ↓
+Executor（读 registry, 拦截 high-risk, 调用 Tool）
+   ↓
+真实 Volcengine OpenAPI
+```
+
+### 3. 枚举三层防御（以 `ClusterStates` 为例）
+
+- **Schema 层**：Tool input 用 `z.nativeEnum(EmrClusterState)`，LLM 收到带 `enum` 的 JSON Schema
+- **Prompt 层**：Tool description 里显式印合法枚举清单
+- **执行层**：Tool `execute()` 内部再做一次大小写 + 中文别名兜底
+
+### 4. OpenAPI 错误可读化
+
+[volcApi.ts](src/services/volcApi.ts) 对火山返回做结构化解析，错误消息会带 `Code / RequestId / body` 等排障必需的上下文，而不是一句干巴巴的 `Internal error`。
+
+### 5. 记忆分文件，互不污染
+
+- `config.json`：**身份**（AK/SK、LLM token）。敏感，少变。
+- `create-cluster-memory.json`：**偏好**（VPC/子网/ZoneId/机型）。常变，可分享模板。
+
+写入时机在 **确认后立刻写**（而不是 API 成功后），哪怕 OpenAPI 挂了，你下次也不用重填网络信息。
+
+---
+
+## LLM 配置提示
+
+Planner 要求必须配置 LLM（OpenAI-compatible `/chat/completions`）。已验证可用的：
+
+- **火山方舟 Ark**：
+  ```
+  endpoint: https://ark.cn-beijing.volces.com/api/v3/chat/completions
+  model:    doubao-seed-character-251128（或其他 doubao 模型）
+  ```
+- **OpenAI 官方**：
+  ```
+  endpoint: https://api.openai.com/v1/chat/completions
+  model:    gpt-4o-mini
+  ```
+- **任何兼容 OpenAI 协议的网关**（Together / Groq / Fireworks / 本地 vLLM 等）
+
+如果模型不支持 `response_format=json_object`，Planner 会退化到 "字符串 JSON + markdown fence 清洗" 的 robust 模式，无需额外改配置。
+
+---
+
+## 故障排查
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| `[ListClusters] The request is missing Version parameter` | `@volcengine/openapi` 需要 `Version` 而非 `version` — 现已修好 |
+| `[ListClusters] Invalid request {0}` | LLM 传了非法字段或类型，Tool 层错误消息会附上 body 预览 |
+| `[CreateCluster] Internal error` | 5xx；抓取 `RequestId` 后去[火山工单](https://console.volcengine.com/workorder/create/)，或用相同参数在 [API Explorer](https://api.volcengine.com/api-explorer/?action=CreateCluster&serviceCode=emr&version=2023-08-15) 复现 |
+| `LLM is not configured` | Planner 没有 rule-based 兜底，请先 `volc-emr-agent config set-llm` |
+| 清理时个别集群报 `marked archived` | 会被 `deleteCluster` 内部捕获，返回 `{ Skipped: true, Reason: "ARCHIVED" }` 并作为该步 `Done` 结果打印，不影响其它集群清理 |
+
+想看更详细的请求/响应？可以临时编辑 [volcApi.ts](src/services/volcApi.ts) 在 `fetchApi(body)` 前后加 `console.error` 打印 body 和 response。
+
+---
+
+## 后续规划
+
+- [ ] 支持 `CreateCluster` 的 `--config file.json` 无交互模式（CI 友好）
+- [ ] 更多 EMR Action：`GetCluster` / `ScaleOutNodeGroup` / `UpdateClusterAttribute`
+- [ ] 多 profile 记忆（`--profile prod/test`）
+- [ ] Tool catalog 热插拔、跨业务目录（非 EMR）
+- [ ] Executor 级别的 retry / rollback / 流式输出
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/dist/agent/agent.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const planner_1 = require("./planner");
+const executor_1 = require("./executor");
+class Agent {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async run(task, options = {}) {
+        const plan = await (0, planner_1.planTask)(task);
+        console.log("\n📋 Plan:");
+        console.log(plan);
+        if (options.dryRun)
+            return;
+        await (0, executor_1.executePlan)(plan, this.ctx, { autoApprove: options.autoApprove });
+    }
+}
+exports.Agent = Agent;

package/dist/agent/executor.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executePlan = executePlan;
+const registry_1 = require("../tools/registry");
+const confirm_1 = require("../runtime/confirm");
+const logger_1 = require("../runtime/logger");
+async function executePlan(plan, ctx, options = {}) {
+    for (const [i, step] of plan.entries()) {
+        const tool = registry_1.toolList.find((t) => t.name === step.tool);
+        if (!tool)
+            throw new Error(`Tool not found: ${step.tool}`);
+        if (tool.riskLevel === "high") {
+            const ok = options.autoApprove
+                ? true
+                : await (0, confirm_1.confirm)(`⚠️ 执行 ${tool.name} (input=${JSON.stringify(step.input)})?`);
+            if (!ok) {
+                (0, logger_1.logStep)(i, `Skipped ${tool.name}`);
+                continue;
+            }
+        }
+        (0, logger_1.logStep)(i, `Running ${tool.name}`, step.input);
+        const result = await tool.execute(step.input, ctx);
+        (0, logger_1.logStep)(i, `Done ${tool.name}`, result);
+    }
+}

package/dist/agent/llmPlanner.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.llmPlanTask = llmPlanTask;
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const registry_1 = require("../tools/registry");
+const emr_1 = require("../tools/emr");
+const llm_1 = require("../runtime/llm");
+function buildToolCatalog() {
+    return registry_1.toolList.map((t) => ({
+        name: t.name,
+        description: t.description,
+        riskLevel: t.riskLevel || "low",
+        inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(t.input, t.name)
+    }));
+}
+function buildSystemPrompt() {
+    const catalog = buildToolCatalog();
+    return [
+        "You are a CLI Agent Planner for Volcengine EMR.",
+        "You MUST NOT execute anything directly.",
+        "Your only job is to output an ordered plan of tool calls.",
+        "",
+        "Available tools (JSON catalog):",
+        JSON.stringify(catalog, null, 2),
+        "",
+        "Response format:",
+        'You MUST output ONLY a JSON object with shape {"steps":[{"tool":"<name>","input":{...}}]}.',
+        "Do NOT include any prose, markdown fences, or explanations.",
+        "The very first character of your reply MUST be `{` and the last MUST be `}`.",
+        "Rules:",
+        "- Only use tools listed above.",
+        "- `input` MUST conform to each tool's inputSchema.",
+        "- For destructive actions (riskLevel=high), only plan them if the user task clearly asks for it.",
+        "- If the task is ambiguous, return at most one safe, read-only step (e.g. listClusters)."
+    ].join("\n");
+}
+function buildUserPrompt(task, context) {
+    const ctx = context ? `\n\nContext:\n${JSON.stringify(context, null, 2)}` : "";
+    return `Task: ${task}${ctx}`;
+}
+function extractJsonObject(raw) {
+    const stripped = raw
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/```\s*$/i, "")
+        .trim();
+    if (stripped.startsWith("{"))
+        return stripped;
+    const start = stripped.indexOf("{");
+    if (start === -1)
+        return stripped;
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = start; i < stripped.length; i++) {
+        const ch = stripped[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === "\\") {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+        }
+        else if (ch === "{") {
+            depth++;
+        }
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0)
+                return stripped.slice(start, i + 1);
+        }
+    }
+    return stripped.slice(start);
+}
+function tryParsePlan(raw) {
+    const jsonText = extractJsonObject(raw);
+    const parsed = JSON.parse(jsonText);
+    const steps = Array.isArray(parsed) ? parsed : parsed?.steps;
+    if (!Array.isArray(steps)) {
+        throw new Error("LLM plan has no `steps` array");
+    }
+    return steps.map((s, i) => {
+        if (!s || typeof s.tool !== "string") {
+            throw new Error(`Step ${i} is missing "tool"`);
+        }
+        return { tool: s.tool, input: s.input ?? {} };
+    });
+}
+function validatePlanAgainstTools(steps) {
+    return steps.map((step) => {
+        const tool = registry_1.toolList.find((t) => t.name === step.tool);
+        if (!tool)
+            throw new Error(`LLM chose unknown tool: ${step.tool}`);
+        const result = tool.input.safeParse(step.input ?? {});
+        if (!result.success) {
+            throw new Error(`LLM produced invalid input for ${step.tool}: ${result.error.message}`);
+        }
+        return { tool: step.tool, input: result.data };
+    });
+}
+async function llmPlanTask(task, llm) {
+    const messages = [
+        { role: "system", content: buildSystemPrompt() },
+        { role: "user", content: buildUserPrompt(task) }
+    ];
+    const content = await (0, llm_1.chatCompletion)(llm, { messages });
+    const steps = tryParsePlan(content);
+    const validated = validatePlanAgainstTools(steps);
+    const expanded = [];
+    for (const step of validated) {
+        expanded.push(step);
+        if (step.tool === "findClustersToCleanup") {
+            const found = await emr_1.emrApi.findClustersToCleanup(step.input || {});
+            for (const c of found) {
+                expanded.push({
+                    tool: "deleteCluster",
+                    input: { ClusterId: c.ClusterId }
+                });
+            }
+        }
+    }
+    return expanded;
+}

package/dist/agent/planner.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planTask = planTask;
+const config_1 = require("../runtime/config");
+const llmPlanner_1 = require("./llmPlanner");
+async function planTask(task, _options = {}) {
+    const llm = (0, config_1.resolveLlmConfig)();
+    if (!llm) {
+        throw new Error("LLM is not configured. Run `volc-emr-agent config set-llm` or set VOLC_LLM_ENDPOINT first.");
+    }
+    return (0, llmPlanner_1.llmPlanTask)(task, llm);
+}

package/dist/agent/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });