huawei-cloud-install-openjiuwenswarm

JiuwenSwarm 本地安装

在当前开发容器中一键本地安装并启动 JiuwenSwarm。 从本地配置（settings.json + 内核密钥环）读取凭据，然后下载、安装、配置并启动服务。

---

概述

功能定位

此 Skill 可在当前开发容器中一键本地安装 JiuwenSwarm，自动完成镜像下载、解压、配置和服务启动的完整工作流。

核心能力

• 自动本地安装：无需手动干预，即可在容器中一键完成从下载到启动的整个流程
• 智能配置：自动读取华为云 API 凭据并配置服务连接信息
• 分阶段进度显示：实时显示各阶段的下载、解压和启动进度
• 多模型支持：默认使用 glm-5.2，支持动态切换可用模型
• 错误重试机制：关键步骤失败后自动重试，确保部署成功

使用场景

• 开发者首次部署 JiuwenSwarm 服务
• 服务重启或迁移后的快速恢复
• 批量环境中的标准化部署工作流

安全特性

• 通过安全渠道读取 API 凭据，不会以明文形式暴露
• 将 .env 文件权限设为 600，仅所有者可读写
• 不存储或传输敏感凭据信息

---

强制调用规则

1. 关键 — 必须首先调用此技能，不得例外：当用户提出类似“部署 JiuwenSwarm/deploy JiuwenSwarm”“安装 JiuwenSwarm/install JiuwenSwarm”“启动 JiuwenSwarm/start JiuwenSwarm”“部署 workswarm/deploy workswarm”“安装 WorkSwarm/install WorkSwarm”“启动 workswarm/start workswarm”的请求时，Agent 必须立即停止当前操作，并严格按顺序运行 5 个阶段脚本（01_download → 02_extract → 03_configure → 04_start → 05_url）。不得直接运行 jiuwenswarm-init、jiuwenswarm-start 或任何其他部署命令。不得以“任务很简单”“我可以手动运行这些步骤”或“用户没有要求使用此技能”等理由跳过。

   各阶段的执行格式：

   Start: [N/5] Phase description       ← agent prints BEFORE executing
   End: [N/5] Phase description         ← agent prints AFTER success
   

   运行阶段之前先打印开始行，然后原样显示脚本输出，最后打印结束行。阶段说明见执行流程。

   错误：如果某阶段以非零状态码退出，最多重试 3 次，然后再手动回退。失败时不得打印结束行。

   最终输出要求（强制）：成功部署后，Agent 必须且只能显示以下消息，不得添加其他命令、解释或文本：

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

   将 {devenvd_id} 替换为实际容器 ID，并将 {port} 替换为 Web 端口（取自 .env 中的 WEB_PORT，在第 3 阶段配置，默认为 5173）。

2. 唯一例外： 只有当阶段脚本以非零状态码退出，且该阶段重试 3 次仍未成功时，Agent 才可以提出放弃自动部署并手动运行命令。

3. 部署目标不匹配的处理： 当用户请求包含不受支持的目标或参数（例如“部署到我的云服务器上/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”）时，Agent 必须先说明此技能的能力边界：

   • 此技能仅支持在当前华为云开发容器（Linux 环境）内本地部署。
   • MODEL_NAME、PORT 和 MIRROR_URL 均不可由用户配置。模型会从 settings.json 自动检测（默认为 glm-5.2）。端口由服务自动分配。镜像 URL 为内置固定地址。 在继续之前，Agent 应询问用户是否接受默认的本地部署。

---

工作流

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]

工作流说明

步骤	名称	执行内容	状态
1	意图识别	检测用户输入是否匹配触发词	自动
2	阶段执行	按顺序运行 5 个阶段脚本（01_download → 02_extract → 03_configure → 04_start → 05_url）	自动
3	进度显示	每个阶段脚本将自身进度输出到 stdout	自动
4	结果输出	从第 5 阶段的输出中解析 URL，并显示最终结论行	自动
5	错误重试	对失败的阶段最多重试 3 次	自动
6	手动回退	重试失败后提示手动部署	手动

---

执行流程

阶段	脚本	说明（用于开始/结束行）
1	01_download.py	正在下载镜像
2	02_extract.py	正在提取镜像
3	03_configure.py	正在配置运行时
4	04_start.py	正在启动服务
5	05_url.py	正在获取 Web URL

---

参数确认

自动检测的参数

此 Skill 会在执行期间自动检测以下参数，无需手动输入：

参数名称	检测来源	默认值	必填	可配置
API_BASE	~/.huawei/hwcloud/settings.json	空	否	否
API_KEY	kernel keyring HWCLOUD-Agent	空	否	否
MODEL_NAME	settings.json current_model	glm-5.2	是	否（从 settings.json 自动检测，无法通过用户命令覆盖）
MODEL_PROVIDER	固定值	DeepSeek	是	否
DEVENVD_ID	容器环境变量	自动获取	是	否
PORT	服务自动分配	5173（前端）	是	否（由 jiuwenswarm-start 服务自动分配）
MIRROR_URL	common.py 中的固定常量	gitcode.com/afeng5267/jiuwenswarm_runtime.git	是	否（内置固定地址）

参数优先级

优先级	来源	说明
1	可用模型列表	如果可用模型中包含 glm-5.2，则优先使用
2	当前配置的模型	settings.json 中配置的 current_model
3	默认值	glm-5.2

注意：无法通过用户命令覆盖 MODEL_NAME。若要更改模型，请直接修改 settings.json。

用户确认点

此 Skill 涉及写入操作（部署、配置、服务启动）。Agent 在开始部署流程前以及每次写入操作前，必须明确征求用户确认。用户始终有权拒绝任何写入操作。

在以下情况下，Agent 会中断并提示用户：

1. 环境不符合要求：操作系统不是 Linux
2. 部署连续失败：某阶段脚本失败超过 3 次
3. 端口被占用：服务端口已被占用

---

运行要求

在华为云开发容器内运行的 Linux 环境。

此技能完全在当前容器内运行，不会创建外部云实例。 运行命令见 Agent 行为规则部分。

---

Agent 行为规则

**重要：**Agent 处理部署流程时，必须遵循以下规则：

1. 静默安装依赖：不要检查或向用户报告 Python／系统依赖。运行任何阶段脚本之前，先静默运行 pip install requests -q（捕获 stdout／stderr，不向用户显示输出）。不要提及此步骤，也不要询问用户，直接执行即可。

2. 不要过早跳过步骤： 按顺序运行 5 个阶段脚本：01_download → 02_extract → 03_configure → 04_start → 05_url。不得跳过任何阶段。

3. 仅在多次出错后提供手动回退方案： 只有在阶段脚本以非零退出码结束，且重试同一阶段 3 次仍未成功后，Agent 才可提出直接运行命令。

4. API 密钥处理： 脚本会从本地配置（settings.json + kernel keyring）读取 API 凭据。若未找到， 部署会输出警告并使用空值继续。服务仍会启动，但在配置 API_KEY 前无法调用 LLM API。

5. 进度显示：使用强制调用规则中的开始／结束格式。 通过 skill action=exec（阻塞调用）运行每个阶段脚本。原样显示脚本 stdout——所有阶段的输出格式均为标准格式。 命令见核心命令。

---

状态处理

状态：错误

脚本输出：

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

Agent 向用户显示：

========================================
❌ 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

最终响应（部署成功后）

重要：这是 Agent 的最终结束语，应在已向用户显示所有进度消息之后输出。它不能替代进度输出。{devenvd_id} 和 {port} 是占位符——请将其替换为脚本输出中的实际值。

Agent 的最终响应必须严格为以下一行（不得添加额外说明、命令或摘要）：

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

---

部署步骤

部署分为 5 个阶段脚本，每个脚本独立运行：

阶段	脚本	说明
1	01_download.py	通过 LFS API 下载镜像（300MB）
2	02_extract.py	将归档文件解压到 /root/tools/jiuwenswarm/
3	03_configure.py	修复 shebang、安装全局命令、初始化工作区、配置 .env
4	04_start.py	启动服务，等待端口就绪
5	05_url.py	输出 Web URL

.env 字段映射

.env 字段	来源	值
API_BASE	settings.json -> providers[*].base_url	云服务 API 端点
API_KEY	内核密钥环 HWCLOUD-Agent（Base64 解码）	可选，仅从密钥环读取
MODEL_NAME	settings.json -> current_model	例如 glm-5.2
MODEL_PROVIDER	固定值	DeepSeek

---

参考文档

此 Skill 的详细参考文档位于 references/ 目录中：

文档名称	路径	说明
IAM 策略	references/iam-policies.md	Skill 所需的 IAM 权限说明
验证方法	references/verification-method.md	部署结果验证步骤
验收标准	references/acceptance-criteria.md	部署成功的验收标准

外部参考资料

• 华为云 CodeDao Skill 开发规范
• Skill 信息安全审核与上架审核规范

---

核心命令

部署命令

通过 skill action=exec 运行：

阶段	脚本	说明
1	["python3", "skill://scripts/01_download.py"]	下载镜像
2	["python3", "skill://scripts/02_extract.py"]	解压归档文件
3	["python3", "skill://scripts/03_configure.py"]	配置运行环境
4	["python3", "skill://scripts/04_start.py"]	启动服务
5	["python3", "skill://scripts/05_url.py"]	获取 Web URL

服务管理

# 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

---

运行时目录结构

所有文件均安装在 /root/tools/jiuwenswarm 下：

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

---

前置条件

依赖项	用途	检查
python3 >= 3.11	脚本执行	python3 --version
tar	解压归档文件	tar --version
ss	检查端口状态	iproute2 的一部分
keyctl	读取内核密钥环（只读）	keyctl --version
~/.huawei/hwcloud/settings.json	云配置（API_BASE、MODEL_NAME）	test -f
内核密钥环 HWCLOUD-Agent	API_KEY 凭据（经过 base64 编码）	keyctl show @s

IAM 权限

此 Skill 需要以下 IAM 权限（详情请参阅 IAM Policies）：

权限	用途	范围
hwcloud:settings:read	读取 Huawei Cloud 配置（API_BASE、MODEL_NAME）	只读
keyring:read	从内核密钥环读取 API_KEY	只读

注意：请勿向用户报告缺少依赖项。脚本会自动静默安装缺少的软件包（requests、keyutils）。直接继续执行即可。

---

全局命令

安装后，以下命令可全局使用（安装到 /usr/local/bin）：

命令	描述
jiuwenswarm-start	启动 JiuwenSwarm 服务
jiuwenswarm-init	初始化工作区（创建 .env）
jiuwenswarm-cli	JiuwenSwarm 命令行界面

---

可用模型

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

---

安全性

1. API 凭据：从本地 settings.json 和内核密钥环读取
2. API 密钥解码：在内部处理，不会向用户公开
3. 获取配置时不会进行网络调用：settings.json 和密钥环均位于本地。
4. .env 权限为 600：只有所有者可以读取和写入。

---

脚本工具

脚本	用途
scripts/common.py	共享常量（路径、端口、LFS 配置）
scripts/01_download.py	阶段 1：通过 LFS API 下载镜像
scripts/02_extract.py	阶段 2：将归档文件解压到 /root/tools/jiuwenswarm
scripts/03_configure.py	阶段 3：配置运行时环境
scripts/04_start.py	阶段 4：启动服务并等待端口就绪
scripts/05_url.py	阶段 5：输出 Web 访问 URL