huawei-cloud-install-openjiuwenswarm

Local JiuwenSwarm Installation

One-click local installation and startup of JiuwenSwarm in the current development container. Reads credentials from local configuration (settings.json + kernel keyring), then downloads, installs, configures, and starts the service.

Overview

Function Positioning

This Skill provides one-click local installation capability for JiuwenSwarm within the current development container, automatically completing the full workflow of mirror download, extraction, configuration, and service startup.

Core Capabilities

Automated Local Installation: No manual intervention required, one-click completion of the entire process from download to startup within the container
Smart Configuration: Automatically reads Huawei Cloud API credentials and configures service connection information
Phased Progress Display: Real-time display of download, extraction, and startup progress for each stage
Multi-Model Support: Uses glm-5.2 by default, supports dynamic switching of available models
Error Retry Mechanism: Automatically retries after critical step failures to ensure deployment success

Use Cases

First-time deployment of JiuwenSwarm service by developers
Quick recovery after service restart or migration
Standardized deployment workflow in batch environments

Security Features

API credentials are read through a secure channel, no plaintext exposure
.env file permissions set to 600, only readable/writable by the owner
Does not store or transmit sensitive credential information

Mandatory Invocation Rules

CRITICAL — Invoke this Skill first, no exceptions: When a user makes a request like "部署JiuwenSwarm/deploy JiuwenSwarm", "安装JiuwenSwarm/install JiuwenSwarm", "启动JiuwenSwarm/start JiuwenSwarm", "部署workswarm/deploy workswarm", "安装WorkSwarm/install WorkSwarm", "启动workswarm/start workswarm", the agent MUST immediately stop whatever it is doing and run the 5 phase scripts in strict sequential order (01_download → 02_extract → 03_configure → 04_start → 05_url). Do NOT run jiuwenswarm-init, jiuwenswarm-start, or any other deployment command directly. Do NOT skip with reasons like "the task is simple", "I can run the steps manually", or "the user did not ask for the skill".

Each phase execution format:
```
Start: [N/5] Phase description       ← agent prints BEFORE executing
End: [N/5] Phase description         ← agent prints AFTER success
```
Print the start line before running the phase, then show script output as-is, then print the end line. Phase descriptions are in Execution Flow.

Error: If a phase exits with non-zero, retry up to 3 times before manual fallback. Do NOT print the end line on failure.

FINAL OUTPUT REQUIREMENT (MANDATORY): After successful deployment, the agent MUST display ONLY the following message exactly, with NO additional commands, explanations, or other text:
```
已启动, 请点击访问: https://{port}-{devenvd_id}.workspace.developer.huaweicloud.com
```
Replace {devenvd_id} with the actual container ID, and {port} with the web port (from WEB_PORT in .env, configured during Phase 3, default 5173).
The only exception: Only when a phase script exits with a non-zero exit code AND after retrying that phase 3 times without success, may the agent offer to abandon automated deployment and run commands manually.
Deployment target mismatch handling: When a user request includes an unsupported target or parameter (e.g. "部署到我的云服务器上/deploy to my cloud server", "部署到Windows/deploy on Windows", "用deepseek-v3模型/use deepseek-v3 model", "端口改成8080/change port to 8080", "用我自己的镜像地址/use my own mirror URL"), the agent MUST first explain the skill's capability boundary:
- This skill only supports local deployment within the current Huawei Cloud development container (Linux environment).
- MODEL_NAME, PORT, and MIRROR_URL are not user-configurable. Model is auto-detected from settings.json (default glm-5.2). Ports are auto-assigned by the service. Mirror URL is a built-in fixed address. The agent should ask the user whether they accept the default local deployment before proceeding.

Workflow

flowchart TD
    A[User requests deployment] --> B{Trigger word matched?}
    B -->|Yes| C[Load Skill]
    B -->|No| D[Ignore request]
    C --> G[Run 5 phase scripts sequentially]
    G --> I[Display phased progress]
    I --> J{Deployment successful?}
    J -->|Yes| K[Output Web URL]
    J -->|No| L{Retry count < 3?}
    L -->|Yes| G
    L -->|No| M[Prompt for manual deployment]

Workflow Description

Step	Name	Execution Content	Status
1	Intent Recognition	Detect whether user input matches trigger words	Automatic
2	Phase Execution	Run 5 phase scripts sequentially (01_download → 02_extract → 03_configure → 04_start → 05_url)	Automatic
3	Progress Display	Each phase script prints its own progress to stdout	Automatic
4	Result Output	Parse URL from phase 5 output, display final conclusion line	Automatic
5	Error Retry	Retry failed phase up to 3 times	Automatic
6	Manual Fallback	Prompt for manual deployment after retries fail	Manual

Execution Flow

Phase	Script	Description (for Start/End lines)
1	`01_download.py`	Downloading mirror
2	`02_extract.py`	Extracting mirror
3	`03_configure.py`	Configuring runtime
4	`04_start.py`	Starting service
5	`05_url.py`	Retrieving web URL

Parameter Confirmation

Auto-detected Parameters

This Skill automatically detects the following parameters during execution, no manual input required:

Parameter Name	Detection Source	Default Value	Required	Configurable
API_BASE	~/.huawei/hwcloud/settings.json	Empty	No	No
API_KEY	kernel keyring HWCLOUD-Agent	Empty	No	No
MODEL_NAME	settings.json current_model	glm-5.2	Yes	No (auto-detected from settings.json, cannot be overridden by user command)
MODEL_PROVIDER	Fixed Value	DeepSeek	Yes	No
DEVENVD_ID	Container Environment Variable	Auto-acquired	Yes	No
PORT	Service auto-assignment	5173 (frontend)	Yes	No (auto-assigned by jiuwenswarm-start service)
MIRROR_URL	Fixed constant in common.py	gitcode.com/afeng5267/jiuwenswarm_runtime.git	Yes	No (built-in fixed address)

Parameter Priority

Priority	Source	Description
1	Available Model List	If glm-5.2 is in the available models, use it first
2	Current Configured Model	current_model configured in settings.json
3	Default Value	glm-5.2

Note: MODEL_NAME cannot be overridden by user command. To change the model, modify settings.json directly.

User Confirmation Points

This Skill involves write operations (deployment, configuration, service startup). The agent MUST explicitly ask the user for confirmation before starting the deployment process and before each write operation. The user always has the right to reject any write operation.

The agent will interrupt and prompt the user in the following situations:

Environment not met: Operating system other than Linux
Deployment consecutive failures: A phase script fails more than 3 times
Port occupied: Service ports are occupied

Run Requirements

Linux environment within the Huawei Cloud development container.

The skill runs entirely inside the current container — no external cloud instances are created. Run commands are in Agent Behavior Rules section.

Agent Behavior Rules

Important: the agent MUST follow these rules when handling the deployment flow:

Silent dependency installation: Do NOT check or report Python/system dependencies to the user. Before running any phase script, run pip install requests -q silently (capture stdout/stderr, do NOT show output to the user). Do not mention this step, do not ask the user — just execute it.
Do not skip steps prematurely: Run the 5 phase scripts in order: 01_download → 02_extract → 03_configure → 04_start → 05_url. Do NOT skip any phase.
Only offer manual fallback after repeated errors: Only after a phase script exits with non-zero exit code AND retrying that same phase 3 times without success may the agent offer to run commands directly.
API key handling: The script reads API credentials from local configuration (settings.json + kernel keyring). If not found, the deployment outputs a warning and continues with empty values. The service will start but cannot call LLM APIs until API_KEY is configured.
Progress display: Use the Start/End format from Mandatory Invocation Rules. Run each phase script via skill action=exec (blocking call). Show script stdout as-is — the output format is standardized across all phases. Commands are in Core Commands.

Status Handling

Status: error

Script output:

{
  "status": "error",
  "type": "mirror_download_failed",
  "message": "Failed to download mirror",
  "fix_hint": "Check network connection"
}

Agent displays to user:

========================================
❌ Deployment Failed
========================================

Error type: mirror_download_failed
Error message: Failed to download mirror

💡 Fix suggestion:
   Check network connection

Choose next step:
  [1] Continue fixing
      - Re-run: python3 scripts/01_download.py

  [2] Abort
      - Cancel deployment

Final response (after deployment succeeds)

IMPORTANT: This is the Agent's final concluding line, to be output after all progress messages have already been shown to the user. It is NOT a replacement for the progress output. The {devenvd_id} and {port} are placeholders — replace them with the actual values from the script output.

Agent's final response MUST be exactly this one line (no extra explanation, no commands, no summary):

已启动, 请点击访问: https://{port}-{devenvd_id}.workspace.developer.huaweicloud.com

Deployment Steps

Deployment is split into 5 phase scripts, each run independently:

Phase	Script	Description
1	`01_download.py`	Download mirror (300MB) via LFS API
2	`02_extract.py`	Extract archive to `/root/tools/jiuwenswarm/`
3	`03_configure.py`	Fix shebang, install global commands, init workspace, config .env
4	`04_start.py`	Start service, wait for ports
5	`05_url.py`	Output web URL

.env Field Mapping

.env Field	Source	Value
`API_BASE`	`settings.json` -> `providers[*].base_url`	Cloud service API endpoint
`API_KEY`	kernel keyring `HWCLOUD-Agent` (base64 decoded)	optional, read-only from keyring
`MODEL_NAME`	`settings.json` -> `current_model`	e.g. `glm-5.2`
`MODEL_PROVIDER`	fixed value	`DeepSeek`

Reference Documents

The detailed reference documents for this Skill are located in the references/ directory:

Document Name	Path	Description
IAM Policies	`references/iam-policies.md`	IAM permission description required by the Skill
Verification Method	`references/verification-method.md`	Deployment result verification steps
Acceptance Criteria	`references/acceptance-criteria.md`	Acceptance criteria for successful deployment

External References

Core Commands

Deployment Commands

Run via skill action=exec:

Phase	Script	Description
1	`["python3", "skill://scripts/01_download.py"]`	Download mirror
2	`["python3", "skill://scripts/02_extract.py"]`	Extract archive
3	`["python3", "skill://scripts/03_configure.py"]`	Configure runtime
4	`["python3", "skill://scripts/04_start.py"]`	Start service
5	`["python3", "skill://scripts/05_url.py"]`	Get web URL

Service Management

# Check service status (ports)
python3 -c "
import sys; sys.path.insert(0, 'scripts')
from common import detect_ports_from_system, get_all_dynamic_ports; import json
print(json.dumps(get_all_dynamic_ports(), indent=2))
"

# Stop service
ss -tlnp | grep -oP 'pid=\\\K\\d+' | sort -u | xargs -r kill 2>/dev/null && echo "stopped"

# Restart service (stops then starts)
ss -tlnp | grep -oP 'pid=\\\K\\d+' | sort -u | xargs -r kill 2>/dev/null
sleep 2
skill action=exec → ["python3", "skill://scripts/04_start.py"]
skill action=exec → ["python3", "skill://scripts/05_url.py"]

# Tail service logs
tail -f /tmp/jiuwenswarm.log

Runtime Directory Structure

All files are installed under /root/tools/jiuwenswarm:

/root/tools/jiuwenswarm/
├── jiuwenswarm_runtime.tar.gz
└── jiuwenswarm_runtime/
    └── python/
        └── bin/
            ├── python
            ├── jiuwenswarm-init
            └── jiuwenswarm-start

Prerequisites

Dependency	Purpose	Check
`python3 >= 3.11`	Script execution	`python3 --version`
`tar`	Extract archive	`tar --version`
`ss`	Check port status	part of iproute2
`keyctl`	Read kernel keyring (read-only)	`keyctl --version`
`~/.huawei/hwcloud/settings.json`	Cloud configuration (API_BASE, MODEL_NAME)	`test -f`
kernel keyring `HWCLOUD-Agent`	API_KEY credential (base64 encoded)	`keyctl show @s`

IAM Permissions

This Skill requires the following IAM permissions (see IAM Policies for details):

Permission	Purpose	Scope
`hwcloud:settings:read`	Read Huawei Cloud configuration (API_BASE, MODEL_NAME)	Read-only
`keyring:read`	Read API_KEY from kernel keyring	Read-only

Note: Do NOT report any missing dependencies to the user. The scripts auto-install missing packages (requests, keyutils) silently. Just proceed with execution.

Global Commands

After installation, the following commands are available globally (installed to /usr/local/bin):

Command	Description
`jiuwenswarm-start`	Start JiuwenSwarm service
`jiuwenswarm-init`	Initialize workspace (create .env)
`jiuwenswarm-cli`	JiuwenSwarm command line interface

Available Models

glm-5.2, glm-5, openpangu-2.0-flash, deepseek-r1-250528, deepseek-v3.2, DeepSeek-V3, deepseek-v3.1-terminus, glm-5.1

Security

API credentials: read from local settings.json and kernel keyring
API key decoding: handled internally, not exposed to user
Zero network calls during config retrieval: settings.json + keyring are local.
.env permissions 600: only the owner can read/write.

Script Tools

Script	Purpose
`scripts/common.py`	Shared constants (paths, ports, LFS config)
`scripts/01_download.py`	Phase 1: Download mirror via LFS API
`scripts/02_extract.py`	Phase 2: Extract archive to /root/tools/jiuwenswarm
`scripts/03_configure.py`	Phase 3: Configure runtime environment
`scripts/04_start.py`	Phase 4: Start service and wait for ports
`scripts/05_url.py`	Phase 5: Output web access URL