命令执行 API（CMD-EXEC-API / Command Execution API）产品系统Vibe Coding

软件交付与运维正从「人工登录主机敲命令」转向「API 化、可编排、可审计」的自动化体系。无论是传统脚本运维、CI/CD 流水线，还是新兴的 AI Agent / 智能体平台，都需要一种安全、可观测的方式在目标机器上执行系统命令：既要支持顺序编排与结果传递，又要能处理长时间运行与交互式（TTY）场景，并留下完整执行记录供排查与合规。

在云原生与混合部署并存的背景下，本地化与边缘侧服务仍大量依赖 Shell、CLI 工具链；将命令执行能力封装为标准 REST API，可降低上层系统直接 `ssh` 或嵌入进程调用的耦合成本，便于与网关、代理、文件服务、部署管理等周边微服务组合。Gartner 等机构持续强调平台工程与自动化运维对交付效率的价值；国内信创与内网隔离环境，也推动「可内网部署的轻量命令中间件」需求增长。

与此同时，AI Coding 与 Agent 调度把「自然语言 → 可执行动作」变成常态：智能体需要稳定、带超时与黑名单约束的命令出口，而不是裸露的本机 Shell。具备白名单/黑名单校验、流式输出、执行日志持久化与 OpenAPI 契约的命令执行服务，正成为开发者平台与本地工具链中的基础组件。长期看，该方向将从「简单远程 exec」演进为「受控执行平面」——覆盖会话隔离、资源限额、审计合规与多租户策略——具备明确的工程落地价值与持续迭代空间。

本项目基于 Java + Spring Boot，对外提供标准 REST API 与 OpenAPI 文档，主要能力包括：

1. **远程命令执行**
通过 `POST /api/commands/execute` 提交命令列表，支持单条或多条顺序执行；每条命令以数组形式传递（命令 + 参数），返回执行状态、结果与 `logId`。

2. **命令编排与结果链式**
支持 `&&`、管道等 Shell 组合；可通过 `${lastExecResult}` 将上一条命令输出代入下一条，便于拼接运维脚本与批处理流程。

3. **流式与长任务**
对 `tail`、`watch`、`top`、`ping` 等可配置流式命令异步执行，立即返回 `logId`，调用方轮询日志接口获取持续输出，避免 HTTP 长时间阻塞。

4. **TTY / 交互式命令**
对需要伪终端的 CLI（如部分 AI CLI）提供 TTY 仿真与配置项（`tty-required`、`streaming-with-flags`）；可选在 macOS Terminal 窗口中打开执行，便于本地可视化调试。

5. **执行日志与审计**
执行记录持久化至 MySQL（状态、输出、退出码、耗时等），通过 `GET /api/commands/log/{logId}` 查询，支撑异步任务跟踪与事后审计。

6. **安全校验与运维配套**
基础黑名单（如 `rm`、`shutdown`、`sudo` 等）、超时与并发限制可配置；提供 Makefile / 启停脚本、Swagger UI、全局 CORS（含 `/v3/api-docs`），便于与前端控制台及产品能力注册体系对接。

**本人职责**：作为核心研发，负责总体架构与迭代交付，包括命令执行编排与结果链式、ProcessBuilder/Shell 双路径执行、流式异步写库与日志查询、TTY 仿真及 macOS Terminal 打开执行、黑名单/超时/并发控制、OpenAPI 与全局 CORS、Makefile 启停运维，以及对 app-deploy-manager、产品能力注册等周边对接与文档/测试脚本输出。

**技术栈**：Java 11、Spring Boot 2.7、Spring Data JPA、MySQL 8、springdoc-openapi、Maven、Logback、Makefile / 启停脚本。

**架构**：分层设计——Controller（入参与 OpenAPI）→ Service（编排与异步调度）→ Executor/Validator（进程执行、Shell 运算符、TTY、安全校验）→ Repository（`command_log` 状态与输出持久化）。对外以 REST 为边界，对内以进程执行 + 数据库日志双通道，支撑同步返回与异步长任务轮询。

**难点与亮点**：① 简单命令走 ProcessBuilder、含 `&&`/`|`/`${lastExecResult}` 时切 Shell，兼顾隔离与编排表达力；② 流式长任务异步落库，配置驱动 TTY/流式命令列表，解决部分 CLI 无伪终端失败问题；③ 结果链式使 API 接近本地脚本编排，便于 Agent 与流水线组合；④ OpenAPI + CORS + 执行审计降低集成与排障成本，支撑多版本持续交付。