huawei-cloud-flexus-l-deploy-jiuwenswarm

重要说明：

1. scripts 目录中的所有 Python 文件均已实现全部功能。请勿创建额外的 py 文件。
2. 请勿修改 scripts 目录中的脚本文件。
3. 请直接依据提供的代码和文档进行操作。无需查阅华为云官方 API 文档。

---

安全执行规则（最高优先级）：

1. 所有脚本都必须通过 skill action=exec 执行，绝不能直接在 shell 中运行
2. 绝不要在对话中打印脚本内容或包含 AK/SK/Token 的命令
3. 绝不要创建临时脚本文件，优先使用内联执行（python -c）
4. 执行失败时，仅返回错误信息，不要重写脚本或打印完整命令
5. AK/SK/Token 必须通过环境变量或 hcloud 配置传递，绝不能出现在对话中
6. 绝不要以交互方式向用户收集华为云凭证。凭证只能通过以下方式获取：
   • hcloud CLI 配置文件（~/.hcloud/config.json）——主要来源，自动检测
   • 通过环境变量提供的临时安全凭证（STS Token）——备用方式
   • 通过环境变量提供的永久凭证——备用方式

---

华为云 Flexus L 实例上的 JiuwenSwarm 部署技能

概述

此技能通过分阶段脚本，为在华为云 Flexus L 实例上部署 JiuwenSwarm（JiuwenClaw）多 Agent 协作平台提供完整的自动化解决方案，涵盖从环境准备到消息渠道配置的全流程自动化。

---

前提条件

1. 华为云账户要求

• 拥有有效的华为云账户，且订阅处于有效状态
• 余额充足，或已配置付款方式
• 目标区域（cn-north-4/cn-east-3/cn-south-1/cn-southwest-2）有可用的 Flexus L 实例配额

2. IAM 凭证

• 具备适当权限的华为云访问密钥（AK）和秘密访问密钥（SK）
• 临时安全凭证（STS Token）：支持使用临时安全凭证。设置 HUAWEICLOUD_SDK_SECURITY_TOKEN 环境变量并同时提供 AK/SK 后，此技能将使用临时凭证进行身份验证。
• 所需的 IAM 权限：请参阅 references/iam-policies.md

3. 环境要求

• 已安装 Python 3.8+ 和 pip
• 建议使用 Python 虚拟环境，以避免系统软件包冲突：

  python3 -m venv .venv && source .venv/bin/activate
  

  如果无法使用虚拟环境，在某些较新的 Linux 发行版上运行 pip 时，可能需要添加 --break-system-packages。
• 所需的 Python 软件包：requests、huaweicloudsdkcore、huaweicloudsdkcoc
• 必须安装 KooCLI（hcloud）并确保其位于 PATH 中（用于查询 IAM/RMS，请参阅 references/api-specs.md）

4. 网络要求

• 可访问华为云 API 的互联网连接
• 安全组规则允许出站 HTTP/HTTPS 流量（端口 80、443）
• 如需访问 Web，部署后需在安全组中开放端口 5173

5. 资源要求

• Flexus L 实例的最低规格：
  • 规格：2c-4g-50g（2 个 vCPU、4GB RAM、50GB 磁盘）或更高
  • 网络：必须具有公网 IP
• 支持的规格：
  • 2c-4g-50g（2 个 vCPU、4GB、50GB）——约 60 CNY/月
  • 2c-4g-70g（2 个 vCPU、4GB、70GB）——约 100 CNY/月
  • 4c-8g-180g（4 个 vCPU、8GB、180GB）——约 170 CNY/月

6. 配置要求

• 用于集成大模型的模型 API 凭证（API_BASE、API_KEY）（Phase 6 必需）
• 如需配置消息渠道，则需要消息渠道凭证（小艺/飞书/钉钉）（Phase 7 必需）

---

架构图

User/Agent      ──────▶│   Flexus L Instance   │──────▶│   JiuwenSwarm App    │──────▶│ Model Config     │ ──────▶│  Channel Config     │
(Skill caller)           (Target Host)                 (Multi-Agent Platform)           (API_BASE/KEY)            (Xiaoyi/Feishu/Dingtalk)

组件说明：

• 用户/Agent：通过自然语言或 API 触发 JiuwenSwarm 部署操作的技能调用方
• Flexus L 实例：华为云弹性云服务器，作为 JiuwenSwarm 部署的目标主机
• JiuwenSwarm App：运行在 Flexus L 实例上的多 Agent 协作平台
• 模型配置：外部大模型服务的配置（API_BASE、API_KEY、MODEL_NAME、MODEL_PROVIDER）
• 渠道配置：消息渠道配置（华为小艺、飞书、钉钉）

---

技能职责

核心功能

1. Flexus L 实例创建 - 调用 Flexus L API 创建实例，支持实例名称、规格、区域等参数
2. 实例状态查询 - 通过 KooCLI（hcloud RMS ListAllResources）查询实例状态、公网 IP、实例 ID
3. COC 远程部署 - 使用华为云 COC（云运维中心）在实例上远程执行部署脚本
4. COC 任务状态查询 - 通过 COC API 查询部署任务的执行状态和结果
5. 系统服务配置 - 配置 systemd 服务以实现开机自启
6. 模型配置 - 配置 API_BASE、API_KEY、MODEL_NAME、MODEL_PROVIDER
7. 消息渠道配置 - 支持三种消息渠道：小艺、飞书、钉钉

典型用例

英文示例：

1. “帮我将 JiuwenSwarm 部署到华为云”
2. “我想在 Flexus L 实例上安装 JiuwenClaw”
3. “如何将飞书机器人添加到我的 JiuwenSwarm？”
4. “我想将 JiuwenSwarm 配置为使用自定义模型”
5. “帮我一键部署 JiuwenSwarm 并配置小艺渠道”

---

工作流

此技能分 7 个阶段执行部署。每个阶段必须完成后才能开始下一阶段。

阶段 1：环境准备

1. 验证华为云凭据（AK/SK）
2. 设置环境变量：PYTHONIOENCODING=utf-8
3. 检查依赖模块：requests、huaweicloudsdkcore、huaweicloudsdkcoc 和 KooCLI（hcloud）
4. 验证凭据有效性（通过 KooCLI hcloud IAM KeystoneListProjects）

阶段 2：创建 Flexus L 实例

⚠️ 执行前需要客户确认！

1. 如果未提供 --region 参数，则交互式提示用户从支持的选项中选择区域
2. 向客户展示实例配置（名称、规格、区域、预估费用）
3. 等待客户确认（回复“confirm”或“agree”）
4. 确认后：获取 Project ID（KooCLI）→ 调用 Flexus L 创建 API → 保存 order_id → 通过 KooCLI 轮询 RMS 以确认完成（每 30 秒轮询一次，默认超时时间为 600s/10 分钟，可通过 --timeout 配置）→ 获取 instance_id、public_ip、ecs_instance_id

阶段 3：通过 COC 远程安装依赖

1. 通过 COC 执行依赖安装脚本
2. 安装基础工具：git、curl、vim、wget、net-tools 等
3. 检查 Python 和 Node.js 环境
4. 等待完成（约 8 分钟）。仅在脚本执行出错时重试。

阶段 4：通过 COC 远程部署 JiuwenSwarm 服务

1. 读取部署脚本模板（assets/deploy_script_template.sh）
2. 通过 COC 在实例上执行完整部署脚本
3. 安装 JiuwenSwarm、配置 systemd 服务并启动服务
4. 等待完成（约 15 分钟）。仅在脚本执行出错时重试。

阶段 5：验证部署结果

1. 查询 COC 部署任务状态
2. 验证 jiuwenswarm 服务正在运行（systemctl is-active）
3. 验证 .env 中设置了 FRONTEND_HOST=0.0.0.0
4. 验证所有端口均绑定到 0.0.0.0：5173、18092、19000、19001
5. 检查服务运行状况（curl localhost:5173 返回 200）
6. 输出 Web 访问 URL：http://{public_ip}:5173
7. 提醒用户配置安全组以允许外部访问

阶段 6：模型配置

1. 以交互方式收集：API_BASE、API_KEY、MODEL_NAME、MODEL_PROVIDER
2. 生成 COC 远程执行脚本：备份 .env，更新 4 个核心参数，设置权限为 600
3. 重启 JiuwenSwarm 服务

阶段 7：消息渠道配置

1. 选择渠道类型：xiaoyi / feishu / dingtalk
2. 根据渠道类型收集配置：
   • xiaoyi：AK、SK、Agent ID
   • feishu：App ID、App Secret
   • dingtalk：Client ID、Client Secret、Allow From
3. 生成 COC 远程执行脚本：备份 config.yaml，更新渠道字段，设置权限为 644
4. 重启 JiuwenSwarm 服务

COC 任务状态查询

按 UUID 查询 COC 执行状态。支持单次查询、详细输出、等待完成和从文件读取。详情请参阅 references/verification-method.md。

状态	描述
READY	就绪
PROCESSING	运行中，需等待
FINISHED	已成功完成
ABNORMAL	执行异常，失败
CANCELED	已取消

---

核心命令

环境设置

# Install dependencies
pip install -r requirements.txt

凭证配置（任选一种）：

选项 A — hcloud CLI 配置（推荐，无需环境变量）：

hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 \
  --cli-access-key=<your-ak> --cli-secret-key=<your-sk>
# For STS token: also add --cli-security-token=<your-token>

选项 B — 环境变量：

export HUAWEICLOUD_SDK_AK=<your-access-key>
export HUAWEICLOUD_SDK_SK=<your-secret-key>
export HUAWEICLOUD_SDK_SECURITY_TOKEN=<your-security-token>  # STS only
export HUAWEICLOUD_REGION="cn-north-4"

部署命令

# 1. Environment preparation
python scripts/prepare_env.py

# 2. Create instance (interactive confirmation)
python scripts/create_instance.py --name jiuwenSwarm-<timestamp> --flavor 2c-4g-50g --wait

# 3. Install dependencies
python scripts/install_deps.py --ip <public_ip>

# 4. Deploy service
python scripts/deploy_service.py --ip <public_ip>

# 5. Verify deployment
python scripts/verify_deployment.py --ip <public_ip>

# 6. Configure model
python scripts/config_model.py --ip <public_ip> --interactive

# 7. Configure message channel
python scripts/config_channel.py --channel xiaoyi --ip <public_ip> --interactive

# 8. Query COC task status
python scripts/query_coc_status.py --uuid <execute_uuid> --verbose

COC 状态查询命令

# Query single task status
python scripts/query_coc_status.py --uuid <execute_uuid>

# Wait for task completion with custom timeout
python scripts/query_coc_status.py --uuid <execute_uuid> --wait --timeout 3600 --interval 30

# Load UUID from JSON file
python scripts/query_coc_status.py --from-file new_instance_info.json

---

参数确认

⚠️ 需要客户确认

执行任何云资源创建操作前，必须获得客户的明确同意！

操作	是否需要确认
创建新的 Flexus L 实例	需要
在现有实例上部署应用	需要
修改云资源配置	需要

确认模板：

============================================================
⚠️ Cloud Resource Creation Confirmation
============================================================
Operation to be executed: Create new Flexus L instance

Instance Specifications:
  - Name: {instance_name}
  - Flavor: {flavor} (2c-4g-50g ~60 CNY/month / 2c-4g-70g ~100 CNY/month / 4c-8g-180g ~170 CNY/month)
  - Region: {region}
  - Estimated Cost: Calculated based on selected flavor

Resources will be created immediately after confirmation.
Please reply "confirm" or "agree" to continue.
============================================================

用户可配置参数

create_instance.py

参数	描述	默认值
--name	实例名称	jiuwenSwarm-{timestamp}
--flavor	实例规格（2c-4g-50g / 2c-4g-70g / 4c-8g-180g）	2c-4g-50g
--region	区域（cn-north-4/cn-east-3/cn-south-1/cn-southwest-2）。如果未指定，将显示交互式选择。	（交互式）
--wait	等待创建完成（每隔 30s 轮询 RMS，查询实例状态）	False
--timeout	使用 --wait 时的最长等待时间（秒）	600（10 分钟）
--confirm	跳过确认提示	False

deploy_service.py

参数	描述	默认值
--ip	实例公网 IP	必填
--wait	等待部署完成	True
--timeout	超时时间（秒）	1800

config_model.py

参数	描述
--api-base	模型 API URL
--api-key	模型 API 密钥
--model-name	模型名称
--model-provider	模型提供方
--ip	实例公网 IP
--interactive	交互式配置

config_channel.py

参数	描述
--channel	渠道类型（xiaoyi/feishu/dingtalk）
--ip	实例公网 IP
--interactive	交互式配置

query_coc_status.py

参数	描述	默认值
--uuid, -u	COC 执行 UUID	必填
--from-file, -f	从 JSON 文件读取 UUID	-
--key, -k	JSON 文件中的 UUID 键名	execute_uuid
--verbose, -v	显示详细输出	False
--wait, -w	等待任务完成	False
--timeout, -t	等待超时时间（秒）	1800
--interval, -i	轮询间隔（秒）	60

---

目录结构

huawei-cloud-flexus-l-deploy-jiuwenswarm/
├── SKILL.md                    # Skill documentation
├── requirements.txt            # Python dependency list
├── scripts/                    # Phased deployment scripts
│   ├── utils.py                # Utility functions
│   ├── prepare_env.py          # Environment preparation
│   ├── create_instance.py      # Create Flexus L instance
│   ├── install_deps.py         # COC remote dependency installation
│   ├── deploy_service.py       # COC remote service deployment
│   ├── verify_deployment.py    # Verify deployment result
│   ├── config_model.py         # Model configuration
│   ├── config_channel.py       # Message channel configuration
│   └── query_coc_status.py     # COC task status query
├── assets/                     # Template files
│   ├── deploy_script_template.sh # Deployment script template
│   ├── jiuwenswarm.service.template # systemd service template
│   ├── config_template.yaml    # Configuration template
│   └── env_template.env        # Environment variable template
└── references/                 # Reference documents
    ├── api-specs.md            # API specifications
    ├── deployment-checklist.md # Deployment checklist
    ├── iam-policies.md         # IAM policies
    ├── verification-method.md  # Verification methods
    ├── acceptance-criteria.md  # Acceptance criteria
    └── troubleshooting.md      # Troubleshooting guide

---

Web UI 访问

访问 Web UI 需要满足两个条件：

1. 服务绑定到 0.0.0.0（通过 .env 中的 FRONTEND_HOST=0.0.0.0 配置）
2. 安全组允许端口 5173（在华为云控制台中配置）

.env 配置（服务端）

/root/.jiuwenswarm/config/.env 中必须使用正确的变量名：

.env 变量	用途	必需值
FRONTEND_HOST	前端 HTTP 绑定地址	0.0.0.0
FRONTEND_PORT	前端 HTTP 端口	5173
WEB_HOST	WebChannel 绑定地址	0.0.0.0
AGENT_SERVER_HOST	AgentServer 绑定地址	0.0.0.0
GATEWAY_HOST	Gateway 绑定地址	0.0.0.0

安全组配置（云端）

1. 登录 Flexus L 控制台
2. 找到你的 JiuwenSwarm 实例 → 实例详情 → 安全/网络
3. 配置安全组规则，开放端口 5173（TCP 入站）

访问 URL：http://<instance_public_ip>:5173 安全警告：开放端口后，JiuwenSwarm Web 界面将可供访问。启用前请评估安全风险。建议仅在需要时临时开放，并在使用后关闭。

---

华为云凭证配置

凭证优先级：hcloud 配置文件 → 环境变量。

选项 1：hcloud CLI 配置文件（推荐）

凭证从 ~/.hcloud/config.json 读取。如果启用了加密（authEncrypt=true），脚本会自动禁用加密以读取明文值。

# Permanent credentials
hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 \
  --cli-access-key=<AK> --cli-secret-key=<SK>

# Temporary credentials (STS Token)
hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 \
  --cli-access-key=<AK> --cli-secret-key=<SK> --cli-security-token=<TOKEN>

无需设置环境变量 — 脚本会直接读取配置文件。

选项 2：环境变量（备用）

环境变量	描述	必需
HUAWEICLOUD_SDK_AK	访问密钥（永久或临时）	是
HUAWEICLOUD_SDK_SK	Secret Key（永久或临时）	是
HUAWEICLOUD_SDK_SECURITY_TOKEN	安全令牌（仅 STS）	否
HUAWEICLOUD_REGION	华为云区域（默认：cn-north-4）	否

参考：https://support.huaweicloud.com/iam_faq/iam_01_0620.html

---

关键 API 端点

服务	端点	用途
Flexus L	https://hcss.{region}.myhuaweicloud.com/v1/light-instances	创建/查询实例
IAM	KooCLI：hcloud IAM KeystoneListProjects --cli-region=<region> [--name=<region>]	获取 Project ID / domain ID（全局服务；凭证有效时，hcloud 会自动解析 domain ID）
RMS	KooCLI：hcloud RMS ListAllResources --cli-region=cn-north-4 --cli-domain-id=<domain_id> [--region_id=<region>] [--type=hcss.l-instance]	查询资源（全局服务：始终使用统一的 cn-north-4 端点，通过 region_id 参数筛选目标区域）
COC	https://coc.myhuaweicloud.com/v1/job/scripts/{script_uuid}	远程脚本执行（全局服务：SDK 客户端始终使用 cn-north-4 端点，每个目标实例的区域信息会包含在请求体中）

支持的区域：cn-north-4（华北-北京四）、cn-east-3（华东-上海一）、cn-south-1（华南-广州）、cn-southwest-2（西南-贵阳一）

系统镜像：Ubuntu 24.04 LTS

---

输出规范

成功输出模板

============================================================
  JiuwenSwarm COC Deployment - Complete
============================================================

Target Instance:
  Name: {instance_name}
  ID: {instance_id}
  IP: {public_ip}

COC Execution:
  Execute UUID: {execute_uuid}
  Status: FINISHED

Deployment Result:
  Web Access: http://{public_ip}:5173
  Port Binding: 0.0.0.0:5173 (verified)
  Submit Time: {submit_time}

NOTE: Huawei Cloud security group must allow inbound TCP 5173
      for external web access. Configure at:
      https://console.huaweicloud.com/smb/?/resource/list

============================================================
[SUCCESS] Deployment task completed!
============================================================

错误输出模板

============================================================
[ERROR] Deployment Failed
============================================================

Error: {error_message}

Suggestions:
  1. Check Huawei Cloud credentials
  2. Verify instance status
  3. Check deployment logs

============================================================

---

参考文档

以下参考文档为此技能提供了详细信息：

文档	描述
references/api-specs.md	Huawei Cloud 服务（Flexus L、IAM、RMS、COC）的 API 规范
references/iam-policies.md	用于部署的 IAM 权限策略和策略 JSON
references/deployment-checklist.md	所有阶段的部署前/后检查清单
references/verification-method.md	验证方法和验收测试流程
references/acceptance-criteria.md	验收标准和签署要求
references/troubleshooting.md	常见部署问题的故障排除指南