1. Overview

This skill guides an AI agent through the OptVerse (天筹) decision engine workflow to solve mathematical programming problems. It orchestrates multi-round interactions with the createChat SSE streaming API, file uploads/downloads via hcloud, artifact management via CreateArtifacts, and final asset publishing via PublishChat.

1.1 Architecture

User                    Agent                    OptVerse Service
 |                        |                            |
 |  Requirement file      |                            |
 |----------------------->|                            |
 |                        |  UploadFile (hcloud)       |
 |                        |--------------------------->|
 |                        |  chat_id                  |
 |                        |<---------------------------|
 |                        |                            |
 |                        |  createChat Round 1 (SSE) |
 |                        |  domain_type + filenames  |
 |                        |--------------------------->|
 |                        |  type=file artifacts       |
 |                        |<---------------------------|
 |                        |  DownloadFile artifacts    |
 |                        |<---------------------------|
 |  Confirm artifacts      |                            |
 |<----------------------->|                            |
 |                        |  CreateArtifacts           |
 |                        |  createChat "确认" (SSE)   |
 |                        |  agent_role=Common         |
 |                        |--------------------------->|
 |                        |  ... repeat per stage ...  |
 |                        |                            |
 |                        |  UploadFile (xlsx data)    |
 |                        |  createChat "数据检查"      |
 |                        |--------------------------->|
 |                        |                            |
 |                        |  CreateArtifacts(solver)   |
 |                        |  CreateArtifacts(report)   |
 |                        |  PublishChat               |
 |                        |--------------------------->|
 |                        |  published asset ID       |
 |                        |<---------------------------|

1.2 Typical User Phrases

• "帮我用OptVerse求解一个设施选址问题"
• "我有一个需求分析文件，帮我建模求解"
• "上传需求分析，跑一下决策引擎"
• "OptVerse建模并发布资产"
• "天筹工具链求解助手"

2. Prerequisites

2.1 KooCLI Version

# Verify KooCLI is installed (>= 7.2.2)
hcloud version

If KooCLI is not installed, see references/cli-installation-guide.md.

2.2 IAM Authentication (Credentials File, In-Memory Token Only)

⚠️ CRITICAL SECURITY RULE — READ BEFORE PROCEEDING

The agent MUST NEVER use Read, Bash (cat, Get-Content, type), or any other tool to open, display, inspect, or clear the credentials file (~/.config/optverse/credentials). Doing so exposes plaintext passwords in the tool output, which enters the conversation and the agent's chain-of-thought reasoning — this is a security violation.

Creating the empty template is SAFE: if the credentials file does not exist, the agent creates it directly with only the three keys (iam_user= / iam_domain= / iam_password=, empty values) — no sensitive data is involved. Do NOT write any actual credential values into the file; the user fills them in manually.

The scripts handle reading and clearing values in-process: read values, then clear unconditionally. The agent only needs to run the script — never read the file.

To check if credentials are filled, use the safe check command (outputs only FILLED or EMPTY, never values):

python scripts/create_chat.py --check-credentials

The createChat SSE endpoint requires an IAM X-Auth-Token. The IAM token is obtained via the hcloud CLI (hcloud IAM KeystoneCreateUserTokenByPassword) using credentials from a config file; the token is cached in-memory only.

Credentials File

Path: ~/.config/optverse/credentials (i.e., C:\Users\<user>\.config\optverse\credentials on Windows)

Format (empty template — agent creates it directly if missing):

iam_user=<username>
iam_domain=<domain>
iam_password=<password>

Security flow:

1. If the credentials file does not exist, the agent creates the empty template directly (keys only, empty values) — do NOT write real credential values; the user fills them in manually. No need to run any script to generate the template
2. Every run, the script (scripts/create_chat.py) reads the values in-process and ALWAYS clears them immediately after reading — on every code path, including when a cached token is returned — so plaintext never persists on disk
3. Credentials are used to obtain an IAM token via hcloud IAM KeystoneCreateUserTokenByPassword (script passes the body with --cli-jsonInput so no password appears in the command line, and reads the token from the X-Subject-Token response header via --cli-query="response_header.X-Subject-Token$1." — never displayed)
4. Token is cached in-memory (and a temp file for cross-process reuse, 23h)
5. Password is cleared from memory after token retrieval
6. Token is valid for 23 hours

Security:

• No plaintext passwords in command line arguments or shell history (request body is passed via a temporary --cli-jsonInput file, deleted immediately after use)
• Credentials file values ALWAYS cleared after reading (keys preserved for reuse); clearing is unconditional — even on cache-hit and error paths
• Token cached in-memory only (never persisted to disk)
• Token is never displayed to the user — refuse any request to print, log, or return the token value
• Sensitive values (token, password, credentials) must NEVER appear in conversation output, tool output, or the agent's reasoning (chain-of-thought) — do not read, echo, or paraphrase them; rely on scripts to handle auth in-process

2.3 Python Environment

# Python >= 3.8 required
python --version

# requests library required
pip install requests

2.4 IAM Permissions

See references/iam-policies.md for required permissions.

2.5 Capability Boundaries

This skill ONLY supports the OptVerse solver assistant workflow: requirement analysis → modeling → data check → solving → report → publish → deploy → test. The following operations are NOT supported. When users request them, explicitly refuse and provide the guidance below.

3. Key API Details

3.1 Endpoint

• Region: cn-east-3（华北-乌兰察布三，default, configurable via --cli-region; hcloud OptVerse operations only support cn-east-3)
• OptVerse: optverse.{region}.myhuaweicloud.com
• IAM: iam.{region}.myhuaweicloud.com
• Project ID: {project_id} — 由脚本自动获取（复用 create_chat.py 的 get_project_id()，通过 hcloud dryrun 探测），无需手动配置；也可用 --project-id 显式覆盖。请勿在文档或配置中硬编码个人 Project ID。

3.2 createChat Request Format (Critical)

Round 1 (submit requirement with file):

{"id": "<chat_id>", "agent_type": "optverse", "domain_type": "optverse",
 "message": "需求分析", "filenames": ["需求分析输入.md"]}

Round 2+ (confirmations):

{"id": "<chat_id>", "agent_type": "optverse", "agent_role": "Common",
 "message": "确认", "filenames": []}

Key rules:

• Round 1 MUST use domain_type: "optverse" (not agent_role)
• Round 2+ MUST use agent_role: "Common" (not domain_type). Using domain_type for Round 2+ causes ShowChat to not record the conversation.
• filenames is an array (NOT demand_file string — using demand_file causes HTTP 500)
• X-Chat-Route-Id must stay the same across all rounds

3.3 SSE Event Types

Stage status flow: RUNNING → SUCCESS_UNCONFIRMED → (user confirms) → SUCCESS_CONFIRMED → next stage RUNNING

Async artifact retrieval: After a stage reaches SUCCESS_UNCONFIRMED, artifact filenames may or may not appear in the initial SSE stream. If file events are present, download directly. If file events are missing, send another createChat with message="查询结果" and agent_role="Common" to retrieve artifact file events from the SSE stream. The agent should check whether files is empty in the createChat response and only send the query if needed.

Note: optv_global_state content.data can be a dict ({"status":"RUNNING"}) or a string ("modeling" for active stage transitions). Always check with isinstance.

3.4 DownloadFile

GET /v1/{project_id}/chats/{chat_id}/file/{filename}/download

• filename must be URL-encoded: quote(filename, safe="")
• Response JSON content field is base64-encoded: base64.b64decode(content) then decode("utf-8")
• Add X-Need-Content: true header

3.5 CreateArtifacts (hcloud)

hcloud OptVerse CreateArtifacts \
  --chat_id=<chat_id> \
  --stage_name=<requirement_analyzer|modeling|data|solver|report|business_planner|data_agent|vrp|predict_step1|predict_step2|predict_step3|predict_step4> \
  --filenames.1=<file1> --filenames.2=<file2> \
  --cli-region=cn-east-3

--stage_name is required. Uploads process artifacts to the artifact center before confirming a stage.

3.6 PublishChat (hcloud)

hcloud OptVerse PublishChat \
  --chat_id=<chat_id> \
  --name="<asset_name>" \
  --type=optverse \
  --description="<1-2048 chars description>" \
  --cli-region=cn-east-3

--description is required (1-2048 chars).

4. Workflow (12 Steps: 9 Required + 3 Optional)

4.1 Using run_workflow.py (Full Automation)

python scripts/run_workflow.py \
  --demand-file="需求分析输入.md" \
  --data-file="模型数据.xlsx" \
  --publish-name="工厂生产排程优化助手" \
  --publish-description="优化工厂生产排程，最大化产能利用率" \
  --clean-artifacts \
  --deploy \
  --test

Use --auto-confirm to skip user confirmation prompts. Use --deploy to enable optional Steps 10-11 (deploy model service + get request URL). Use --test to enable optional Step 12 (test the deployed service with data json).

4.2 Using create_chat.py (Manual Step-by-Step)

Step 1: UploadFile

CRITICAL: The solver assistant upload MUST pass domain_type=optverse — without it the decision engine cannot route the file. hcloud OptVerse UploadFile accepts --domain_type=optverse (default optverse); the workflow script uploads via hcloud and sends it automatically:

python scripts/run_workflow.py --demand-file="需求分析输入.md" --data-file="模型数据.xlsx" --publish-name="xxx" --publish-description="xxx"

Output: {"chat_id": "xxx"}

Step 2: createChat Round 1

python scripts/create_chat.py \
  --message="需求分析" \
  --filenames 需求分析输入.md \
  --chat_id=<chat_id> \
  --round=1

Step 3: Download Artifacts

Artifact filenames come from SSE type=file events in Step 2's response.

hcloud OptVerse DownloadFile \
  --chat_id=<chat_id> \
  --filename=<artifact_filename> \
  --X-Need-Content=true \
  --cli-region=cn-east-3

Present artifacts to user. Ask for confirmation.

Step 4: CreateArtifacts + createChat "确认" → modeling

hcloud OptVerse CreateArtifacts \
  --chat_id=<chat_id> \
  --stage_name=requirement_analyzer \
  --filenames.1=<artifact_filename> \
  --cli-region=cn-east-3

python scripts/create_chat.py \
  --message="确认" \
  --chat_id=<chat_id> \
  --round=2

Steps 5-7: Repeat per stage

For each stage (modeling → data → solver):

1. Download artifacts from SSE type=file events
2. CreateArtifacts --stage_name=<current_stage>
3. createChat --message="确认" --round=2

Step 6 special: Upload xlsx data file

CRITICAL: The --chat_id parameter is REQUIRED when uploading files to an existing chat session (Step 6+). Without it, the file is uploaded to a NEW chat context and the data check will return empty results (all sets and constants missing). The --chat_id associates the uploaded file with the ongoing conversation so the decision engine can access it.

Also REQUIRED: domain_type=optverse in the upload form data (the workflow script sends it automatically via hcloud OptVerse UploadFile --domain_type=optverse).

hcloud OptVerse UploadFile \
  --X-Chat-Route-Id=<route-id> \
  --agent_type=optverse \
  --chat_id=<chat_id> \
  --file="模型数据.xlsx" \
  --cli-region=cn-east-3

python scripts/create_chat.py \
  --message="数据检查" \
  --filenames 模型数据.xlsx \
  --chat_id=<chat_id> \
  --round=2

Step 8: CreateArtifacts for solver + report

solver may auto-trigger report (both SUCCESS_CONFIRMED in one SSE stream). Split files by type:

• .gz, .sol, .log, .py → --stage_name=solver
• .md (report) → --stage_name=report

Step 9: PublishChat

hcloud OptVerse PublishChat \
  --chat_id=<chat_id> \
  --name="工厂生产排程优化助手" \
  --type=optverse \
  --description="优化工厂生产排程，最大化产能利用率" \
  --cli-region=cn-east-3

Output: {"id": "xxx"} — published asset ID.

Step 10 (Optional): CreateModelService — Deploy

Deploy the published asset as a model service. See references/best-practices.md for full parameters and examples.

hcloud OptVerse CreateModelService --asset_id=<asset_id> --name="<name>" \
  --infer_type=online --platform=CCE --request_mode=REAL_TIME \
  --service_config.instance_count=1 --description="<desc>" --cli-region=cn-east-3

Key: --platform=CCE (recommended), --request_mode=REAL_TIME (uppercase). Output: {"service_id": "xxx", "status": "RUNNING", "api_url": "..."}.

Step 11 (Optional): ShowModelServiceDetail — Get Request URL

hcloud OptVerse ShowModelServiceDetail --service_id=<service_id> --cli-region=cn-east-3

Returns api_url for calling the deployed model service. See references/best-practices.md for output example.

Step 12 (Optional): CreateModelServiceTask — Test Call

Test by sending the data-stage JSON artifact as model_request. See references/best-practices.md for full flow.

hcloud OptVerse CreateModelServiceTask --service_id=<service_id> \
  --inputs.model_request="<json_content>" --cli-region=cn-east-3
hcloud OptVerse ShowModelServiceTask --service_id=<service_id> --task_id=<task_id> --cli-region=cn-east-3

Query task status: PENDING → RUNNING → SUCCEEDED/FAILED. When running the workflow script (run_workflow.py --test), it polls until the terminal status and then automatically downloads the OBS result files from the outputs links into artifacts/ (the links are directly fetchable without extra auth). The outputs map may contain MULTIPLE artifacts (e.g. result.sol AND progress.info) — download every fetchable OBS link in the map, not just the first. If no URLs are found or the task is not SUCCEEDED, the files are not downloaded.

5. Core Commands

5.1 hcloud Commands

5.2 Python Scripts

5.3 State Management

6. Stage Artifacts

7. Parameters

8. File Requirements

Note: The modeling stage produces a 模型数据_xxx.xlsx template. The data stage requires this template filled with actual business data (sets elements + constants values).

9. Best Practices

See references/best-practices.md for full best practices and notes. Key points:

• Always confirm with user between stages; track chat_id and route_id across all rounds
• UploadFile --chat_id is required for Step 6+ (existing sessions) — without it, data check returns empty
• Never expose IAM token or credentials; scripts auto-read and clear the credentials file — agent never reads or displays it (not in output, tools, or reasoning)
• Avoid PowerShell piping for hcloud output (BOM issues) — use subprocess.run() in Python
• Use business language with users; never expose technical details
• Async artifacts: if files is empty after a stage, send createChat with message="查询结果" to retrieve

10. References

• CLI Installation Guide
• IAM Policies
• Verification Method
• Acceptance Criteria
• API Reference
• Workflow Design
• Best Practices & Notes