通用 Shell 部署器

用途

使用该技能执行基于命令行的跨平台环境搭建。

目标节点可能包括：

• 本地 Windows、Linux 或 macOS 系统
• 通过 SSH 连接的远程 Linux 或 macOS 系统
• 通过 PowerShell Remoting 或其他已配置命令桥接方式连接的远程 Windows 系统

该技能以配置为中心。在规划或执行任何变更前，务必先阅读同目录下的 config.json 文件。

必需输入

执行任何操作前，需明确以下信息：

1. 目标节点
2. 目标服务或配方（recipe）
3. 期望执行的动作：install、configure、start、stop、restart、status、verify、uninstall
4. 是否允许提权执行
5. 该任务是仅限本地、仅限远程，还是混合模式

若其中任一信息不明确，请向用户确认。

配置契约（Config Contract）

读取同目录下的 config.json 文件，并将其作为以下内容的唯一可信来源：

• 默认行为
• 节点定义
• 配方偏好
• 执行历史
• 当前状态

在取得实质性进展后，及时更新 config.json，以便后续运行可从上一次已知状态继续执行。

执行工作流

1. 加载配置

读取 config.json 并解析以下字段：

• defaults
• nodes
• recipes
• state

若所请求的节点不存在，应先询问用户是否创建该节点，再继续后续流程。

2. 选择节点

按名称选择节点，并严格遵循该节点定义中的以下属性：

• transport
• os
• shell
• workdir
• packageManager
• 权限策略（privilege policy）

若节点中声明 enabled: false，则未经用户明确确认不得启用该节点。

3. 选择配方

若存在命名的配方（named recipe），则优先将其作为默认实现方案。

优先采用该配方中定义的：

• 安装方式
• 软件包名称
• 服务名称
• 端口
• 环境变量
• 健康检查方式

若无匹配配方，则基于节点默认值构建最小可行计划，并确保其幂等性（idempotent）。

4. 执行前规划

在对系统进行任何变更前，须清晰陈述具体执行计划，包括：

• 将使用的节点
• 将采用的传输方式（transport）
• 将执行的具体命令
• 成功的判定标准
• 将被更新的状态字段

高风险操作必须拆分为多个小步骤执行。

5. 按传输方式执行

本地执行

在对应平台的正确 shell 中直接运行命令：

• Windows：优先使用 powershell
• Linux/macOS：优先使用 bash

SSH 执行

使用 ssh 命令执行，尽可能避免交互式操作。

推荐实践包括：

• 显式指定用户名
• 显式指定主机名
• 使用幂等的 shell 命令
• 分批执行小规模命令，而非一次性提交巨型脚本

Windows 远程执行

使用节点定义中配置的命令桥接方式。除非用户另行指定，否则默认采用 PowerShell Remoting 语义。

6. 每步均需验证

完成安装或配置后，至少通过以下一项或多项方式进行验证：

• 软件包版本号
• 服务运行状态
• 监听端口是否就绪
• 相关进程是否存在
• HTTP 健康检查端点响应
• 存储服务登录或测试查询结果

未获得明确验证信号前，不得标记该步骤为完成。

7. 持久化状态

将有价值的状态信息写回 config.json，例如：

• state.lastSelectedNode
• state.lastRecipe
• state.lastAction
• state.lastResults
• state.installations
• state.services

失败记录须包含时间戳及简明错误摘要。

跨平台规则

• 优先使用节点配置中声明的包管理器（package manager）。
• 不得假定 Windows 系统支持 sudo。
• 不得假定所有 Linux 主机均支持 systemctl。
• 除非配置中明确声明，否则不得假定 macOS 已安装 Homebrew。
• 对于容器部署，若节点或配方中已配置 docker compose，则优先使用该方式。
• 对于直接二进制安装，仅当用户明确要求或配方强制指定时，才锁定版本号。

安全规则

• 除非用户明确授权，否则禁止执行具有破坏性的命令。
• 重装过程中，未经用户要求重置，禁止清空数据目录。
• 数据库部署时，优先创建专用用户与专用数据目录。
• 涉及互联网下载时，优先使用配方中记录的官方发布 URL，或经用户确认的地址。
• 执行需提权的命令前，必须清晰提示用户即将进行权限提升操作。

推荐的状态结构（State Shape）

更新 config.json 时，请统一采用如下字段组织方式：

• nodes..connection：稳定连接元数据
• nodes..overrides：节点特有行为覆盖项
• recipes.：可复用的安装/配置模板
• state.installations..：安装状态与版本信息
• state.services..：服务运行状态与健康状况
• state.lastResults.：最近一次操作摘要

建议覆盖的配方类型

请为常见环境服务维护标准化配方：

• redis
• postgresql
• mysql
• minio
• zlmediakit
• docker
• nginx
• nodejs
• python
• java

每个配方应明确定义：

• 各平台对应的软件包名称
• 各平台对应的服务名称
• 默认端口
• 安装步骤
• 配置文件路径与关键参数
• 验证命令

响应风格

使用该技能时，请遵循以下响应规范：

1. 简要确认目标节点与操作意图
2. 执行前展示完整计划命令列表
3. 以小步、可验证的方式逐步执行
4. 总结实际变更内容
5. 说明哪些 config.json 字段已被更新

示例请求

• “在本机 Windows 安装 MinIO 并开机启动”
• “在远程 Ubuntu 机器安装 PostgreSQL 16”
• “帮我给 dev-linux-01 安装 ZLMediaKit 并验证 1935 和 8080 端口”
• “在 macOS 上补齐 Docker、Redis、Node.js 开发环境”
• “更新 prod-edge-02 上的 MinIO 配置但不要删除数据”