huawei-cloud-vod-collector
Invoke this skill to capture poor experiences and distill them into high-value requirements (Voice of Developer). Use when user encounters any Huawei Cloud related issues, like user expresses dissatisfaction, encounters errors, or wants to report issues/suggestions.Triggers include: "体验差","反馈问题","反馈建议","这个有bug","拒绝了请求","报告问题","反馈体验","report a problem","report a suggestion","bug report","poor experience","voice of developer"
VoD (Voice of Developer) Collector Skill
Script execution: All scripts are located in
<SKILL_DIR>/scripts/. You must wrap every script execution withskill-quality-cli run --skill-name huawei-cloud-vod-collector --(Mandatory mandate below); never run them bare.<SKILL_DIR>= directory containing this SKILL.md..vod/is relative to CWD (project working directory).
Overview
The VoD (Voice of Developer) Collector captures poor developer experiences and issues encountered while using Huawei Cloud tools or services. It prepares high-quality requirements or issue reports (GitCode issues) for product and engineering teams. The skill is declarative: it collects feedback with scripts and a hooks-based capture pipeline, deduplicates (in-session and cross-session), sanitizes, delivers prioritized issues to a GitCode repository, and can additionally fan a delivery notification out to a webhook or email channel.
Dependency: Quality telemetry is collected automatically via skill-quality-cli (installed by <SKILL_DIR>/scripts/ensure_cli.sh if absent).
Core Commands
Common CLI examples grouped by function (all scripts under <SKILL_DIR>/scripts/):
- Capture
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/md_io.py write-feedback --output .vod/feedbacks/
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_sanitize.py file --path <file>
-
Extract / Edit (use
write-feedbackto update fields or edit feedback files directly) -
Deliver
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py deliver --feedback-id <id> --feedbacks-dir .vod/feedbacks
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py deliver --feedback-id <id> --feedbacks-dir .vod/feedbacks --force
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py update-status --feedback-id <id> --status delivered --feedbacks-dir .vod/feedbacks
- Cross-session dedup / notification
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py dedup-scan --feedbacks-dir .vod/feedbacks --feedback-id <id> --lookback 10 --json
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py notify --feedbacks-dir .vod/feedbacks --feedback-id <id> --channel auto --json
- Auto-login (only when
deliverreturnsneed_login)
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- bash <SKILL_DIR>/scripts/vod_install.sh
# Optional: pin a trusted checksum explicitly (skips the bundled known-version manifest)
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- bash <SKILL_DIR>/scripts/vod_install.sh --sha256 <file>
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py server-start
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- curl -s -X POST http://localhost:8080/login/start
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py login-wait --session-id <session_id>
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py server-stop --pid <pid>
Parameter Confirmation
The following parameters can be configured by users or integrators:
--feedbacks-dir/--output: Feedback storage directory.md_io.py write-feedbackwrites via--output;vod_deliver.py(deliver/update-status/dedup-scan/notify) reads via--feedbacks-dir. Both are usually passed as.vod/feedbacks/— neither script defines a default, so each must be given explicitly (equivalent per-command naming).--atomgit-home/ATOMCODE_HOME: AtomGit-GO configuration directory, default~/.atomcode.VOD_ATOMGIT_TOKEN: Environment-variable token override. When set to a non-empty value it takes precedence over${ATOMCODE_HOME:-$HOME/.atomcode}/auth.toml, so no credential has to be persisted to disk.delivery.channels.gitcode.repo_url: Target repository URL — read only fromassets/config.yaml.capture.dedup_window_sec: In-session deduplication window in seconds.storage.max_feedbacks_per_session: Maximum stored feedbacks per session (default 5).--lookback <N>:dedup-scanscan depth — the N most recently modified feedbacks (default 10).--force/--skip-dedup:deliverduplicate-gate controls.--forcedelivers even when a strong cross-session duplicate candidate is found (and is also required to re-deliver a feedback whosedelivery_statusis alreadydelivered, which otherwise returnsalready_delivered);--skip-dedupskips the pre-delivery duplicate scan entirely.--channel webhook|email|auto:notifytransport override (defaultauto→delivery.channels.notification.type).--dry-run:notifylists the payloads that would be sent without sending anything.- Logging/Debug: Optional flags inside scripts to enable additional logging or debug modes.
Before delivery or auto-login, ensure the repo_url is provided via assets/config.yaml and is not inferred from git remote.
References
See additional implementation details and integration guides in the repository:
- references/hooks-setup.md
- references/openclaw-integration.md
- references/cli-installation-guide.md
- references/dedup-and-notify.md
- assets/VOD_FEEDBACKS.md
- assets/VOD_ISSUE.md
- references/acceptance-criteria.md
- references/verification-method.md
Prerequisites
Python dependencies
Install required Python packages before running any scripts:
pip install -r <SKILL_DIR>/requirements.txt
Windows support
Windows is a supported platform (scripts/vod_install.ps1; the login server and its shutdown path use Windows process APIs such as taskkill).
-
The POSIX ownership/permission checks on
auth.toml(owner uid viast_uid/os.getuid(), group/other write bits) are skipped whenos.name == "nt"— on Windows the file is protected by the directory ACL instead. Older revisions raisedAttributeError: module 'os' has no attribute 'getuid'and crashed (#959);delivernow returns its structured JSON result (success/need_login/ error) on Windows as well. -
skill-quality-cli— ensured bybash <SKILL_DIR>/scripts/ensure_cli.sh(idempotent, skips if present; on Windows run it from Git Bash withpython3onPATH— Git for Windows only shipspython/py). See references/cli-installation-guide.md.- Upgrade:
skill-quality-cli runonly upgrades when the installed version is below the platform's minimum supported version (setSKILL_QUALITY_NO_AUTO_UPGRADE=1to disable); otherwise upgrade manually withskill-quality-cli upgrade. - Disable telemetry report: set
SKILL_QUALITY_REPORT=0
- Upgrade:
**⚠️ Mandatory: every script execution in this skill MUST be wrapped with
skill-quality-cli run --skill-name huawei-cloud-vod-collector --(e.g.skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/md_io.py write-feedback ...) — bare invocations ofpython/md_io.py/vod_sanitize.py/vod_deliver.py/vod_install.*/curlare strictly forbidden. Directhcloudinvocations are likewise forbidden: everyhcloudcall goes throughscripts/hcloud-run.sh, which wraps it withskill-quality-cli runand injects--cli-region(see KooCLI region). Disable telemetry (opt-out):SKILL_QUALITY_REPORT=0. Bootstrapping exception: the installer itself —ensure_cli.sh— may be executed bare (unwrapped) whenskill-quality-cliis not yet installed; all other script executions must be wrapped once the CLI exists.
Workflow
Phase 1: Capture
Triggered by hooks (tool errors, user rejection, proactive reports). Generates raw feedback.
1.1 Generate Raw Feedback
- Write the feedback file —
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/md_io.py write-feedback --output .vod/feedbacks/(see--helpfor all params) - Sanitize — secrets are redacted automatically by
write-feedback. To manually sanitize an existing file:skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_sanitize.py file --path <file>
1.2 Deduplication
- In-session (during write): Same
session_id + command + error_typewithincapture.dedup_window_sec→ incrementrecurrence_countinstead of writing a new file. - Cross-session (before Phase 3 delivery): scan the 10 most recent feedbacks and let the Agent (LLM) judge duplicates. Run:
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py dedup-scan --feedbacks-dir .vod/feedbacks --feedback-id <id> --lookback 10 --json
The command takes the most recently modified feedbacks (mtime, descending, --lookback default 10) and, for the given --feedback-id, reports the duplicate candidates: {"success":..., "scanned":N, "target":{...}, "candidates":[{id, file, session_id, feedback_type, error_type, status, delivery_status, recurrence_count, title, signature, signature_match, score, reason, is_strong_duplicate}], "strong_duplicates":[...], "should_deliver":true|false, "llm_prompt":"..."}. A candidate from a different session_id is reported when the normalized error-text signature matches or score ≥ 0.6; only signature-matching candidates whose peer is already closed out can block delivery. The Agent makes the final semantic call. On a match, do not deliver — merge into the existing feedback instead. See references/dedup-and-notify.md.
Phase 2: Extract
Note: This phase is executed by the Agent (LLM) directly — there is no independent extraction script (
scripts/intentionally contains novod_extract.pyor equivalent). The Agent enriches the feedback file usingwrite-feedbackto update fields.
Enrich feedback with context using LLM, then write all fields directly into the feedback file.
Each field maps to a specific section in the markdown file:
error_stack— Extract traceback/exit code from error context →## Error Information → error_stackuser_intent— What the user wanted to do (e.g. "create OBS bucket"), NOT how →## Context → user_intentscenario— Reconstruct what the user was doing →## User Report → scenarioexpected_behavior— What the user expected. From dialog if explicit, otherwise infer from error →## User Report → expected_behaviorproduct_name— Priority: annotation > agent_action > error_message → Title prefix【Product】environment— Platform, OS, session ID, Python version →## Context → environmentdialog_context— 3-5 key turns around the problem point, preserve original language →## Context → dialog_context
Use write-feedback again to update fields, or edit the markdown file directly.
Phase 3: Deliver
3.1 Sync to GitCode Issue
⚠️
repo_urlcomes only fromassets/config.yaml→delivery.channels.gitcode.repo_url. Never usegit remote, never ask the user.
Step 0 — cross-session dedup gate (required before delivering):
- Run
dedup-scanfor the target feedback (see Phase 1.2) and inspectcandidates+should_deliver. - If a candidate is the same problem (different session, and either a matching normalized error-text
signatureorscore≥ 0.6, semantically equivalent), do not deliver — update the existing feedback instead. - Otherwise deliver normally.
deliverre-checks this gate: without--forceit returns{"success":false,"error":"duplicate_suspected","duplicate_of":"<ID>","candidates":[...]}when a strong candidate exists —signature_match == true, a different session, and a peer already closed out (peerdelivery_status == "delivered", or peerstatusinpromoted/resolved; the status enum has nodeliveredvalue) — and no issue is created. Score-only candidates (signature_match == false) never block delivery. Re-run with--forceonly after the LLM has confirmed the candidate is a different problem;--skip-dedupskips the gate.
Single delivery — submit one feedback as a GitCode Issue:
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py deliver \
--feedback-id <id> \
--feedbacks-dir .vod/feedbacks
Update status — mark a feedback as delivered (or other status):
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py update-status \
--feedback-id <id> --status delivered --feedbacks-dir .vod/feedbacks
Auto-login — when deliver returns "need_login": true, perform the following:
Pre-check (MCP shortcut — try first): Before starting the QR-code login flow below, check whether the
devspace-connectorMCP server exposes agitcode_create_issue(orcreate_issue) tool. If the tool exists AND is callable, use it to create the issue directly — thedeliverresponse now carriesrepo_url,issue_title, andissue_bodyfor this purpose. After the MCP tool creates the issue, runupdate-status --status deliveredand skip the QR-code login steps 1–8 below.If the connector is unavailable — for ANY reason (server not connected, not configured, tool absent, or call fails): directly fall back to the QR-code login flow below. Do NOT ask the user whether to connect the MCP server or present any choice — proceed silently to step 1 of the fallback. Any attempt to "enable/connect the connector" is out of scope here and must NOT be offered as an option.
CRITICAL: Before installation, MUST tell the user:
- This login uses the open-source project AtomGit-GO (MIT license).
- Source: https://gitcode.com/weixin_45218422/AtomGit-GO
-
Check & install: Execute
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- bash <SKILL_DIR>/scripts/vod_install.sh(Linux/macOS) orskill-quality-cli run --skill-name huawei-cloud-vod-collector -- powershell <SKILL_DIR>/scripts/vod_install.ps1(Windows).- The upstream repository publishes pre-built archives without
.sha256sidecars; the installer verifies them against the bundled known-version manifest (scripts/vod_install_checksums.txt). Pass--sha256 <file>(POSIX) /-Sha256File <file>(Windows) to pin a trusted checksum explicitly. If no checksum source is available or the archive does not match the manifest, the installer refuses that archive and falls back to a source build (Go >= 1.22 required) instead of aborting the whole install path.
- The upstream repository publishes pre-built archives without
-
Start server:
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py server-start→ getpidfrom JSON output -
Initiate QR login:
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- curl -s -X POST http://localhost:8080/login/start→ getlogin_url,qr_code,session_idfrom JSON -
Show QR to user: Display the
login_urland ASCIIqr_code. Say: "🔐 First-time login requires AtomGit authorization. Scan the QR code or open the URL in your browser." -
Wait for authorization:
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py login-wait --session-id <session_id>— blocks until scanned (up to 60s). Do NOT ask the user whether they scanned; just wait. -
On
SCAN_SUCCESS, proceed to step 7.CRITICAL: After successful authorization, MUST output the Security Notice:
- Security Notice: The AtomGit-GO login flow persists the token only to
${ATOMCODE_HOME:-$HOME/.atomcode}/auth.toml(owner-readable only, mode 0600). Anyone with file access can impersonate you — do not share this file. - Note: Stored only in the local AI Shell environment. It will not be uploaded to any external server.
- Deletion: Manually delete the file, or it will be cleaned up when the environment resources are reclaimed.
- Security Notice: The AtomGit-GO login flow persists the token only to
-
Stop server:
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py server-stop --pid <pid> -
Re-run the original
delivercommand.
Notification Channels (notify)
Optional fan-out of pending feedbacks to a webhook or an email recipient, in addition to the GitCode issue. Configure delivery.channels.notification in assets/config.yaml (ships enabled: false; enable it explicitly before use), then run:
skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py notify --feedbacks-dir .vod/feedbacks --feedback-id <id> --channel auto --json
--channel webhook|email|auto(optional, defaultauto→delivery.channels.notification.type);--feedback-idlimits the run to one feedback.--dry-runlists the payloads without sending.- Pending first: the command checks for pending feedbacks before anything else. With nothing pending it returns
{"success":true,"pending":0,"sent":[]}without resolving the AtomGit token and without triggering the login flow — never prompt the user to log in just to learn there is nothing to send. Pending = notdiscarded, not alreadydelivered, and nonotified_atrecorded yet; a successful send recordsnotified_atunder## Delivery, so repeat runs stay idempotent. webhook: HTTPPOSTwith a JSON body towebhook.url, usingwebhook.headers.email: SMTP with TLS viaemail.smtp_host/email.smtp_port/email.recipients. Both honorretry_policy(max_retries,backoff_base_sec,backoff_max_sec).- Full JSON contract and configuration reference: references/dedup-and-notify.md.
Behavioral Constraints
- Cancel: Clean up current file only. Never delete
.vod/or other records. - Decline: Skip silently, do not suppress future triggers.
- Validation: Only product/service issues. No empty/minimal content ("test", "hello").
- Cross-session dedup: run
dedup-scanbeforedeliverand skip delivery when the Agent judges a candidate to be the same problem; usedeliver --forceonly after that judgment, and--skip-deduponly when the gate has deliberately been bypassed. - Session limit: Max
storage.max_feedbacks_per_session(default 5). Exceeded → inform user. - Updates: In-place only. ID immutable. State machine:
open → delivered → promoted → resolvedoropen → delivered → discarded(deliveredis the post-delivery state written byupdate-status --status delivered). - Auto-init:
.vod/created on first use. Never overwritten. - Quality telemetry (mandatory): every script/command execution is wrapped with
skill-quality-cli run --skill-name huawei-cloud-vod-collector --; disable viaSKILL_QUALITY_REPORT=0(opt-out).
Storage
- Path:
<CWD>/.vod/feedbacks/ - Format:
VOD-YYYYMMDD-NNNN.md
CLI Reference
| Parameter | Description |
|---|---|
--atomgit-home <path> | AtomGit-GO config dir (default: ~/.atomcode or $ATOMCODE_HOME) |
--feedback-id <id> | Feedback ID to deliver/update, or the target of dedup-scan / notify |
--feedbacks-dir <path> | Path to .vod/feedbacks/ |
--lookback <N> | dedup-scan: number of most recent feedbacks to scan (default 10) |
--json | Reserved for compatibility only — the code never reads it; dedup-scan / notify always print JSON |
--force | deliver: deliver despite a strong cross-session duplicate candidate, or re-deliver an already delivered feedback |
--skip-dedup | deliver: skip the pre-delivery duplicate scan |
--channel <webhook|email|auto> | notify: transport override (default auto) |
--dry-run | notify: list the payloads that would be sent without sending |
KooCLI region
KooCLI invocations accept the global parameter --cli-region=<region>
(e.g. hcloud ECS ListServers --cli-region=cn-north-4). In this skill all
hcloud calls go through scripts/hcloud-run.sh, which injects
--cli-region automatically from the HW_CLI_REGION environment variable
when set (and the command does not already pass it).
Token Configuration
- Token source, in priority order:
VOD_ATOMGIT_TOKENenvironment variable — used directly when set to a non-empty value;auth.tomlis not read and the token is never persisted to disk.- Token from open-source AtomGit-GO, saved in plaintext to
${ATOMCODE_HOME:-$HOME/.atomcode}/auth.toml.
- Plaintext storage is upstream behavior (#114 问题 9). This skill cannot change how AtomGit-GO writes
auth.toml; its mitigations are:- POSIX: the parent directory must be owned by the current user and not group/other-writable; symlinks and non-regular files are refused; the file mode is tightened to
0600before the token is read, and reading is refused when it cannot be tightened. - Windows (
os.name == "nt"): POSIX ownership/mode checks are skipped and the file is protected by the directory ACL instead. VOD_ATOMGIT_TOKENavoids writing a credential to disk, which is a real improvement on shared hosts and containers — but on POSIX a same-uid process (including a child process) can still read the variable from/proc/<pid>/environ, so it is not a strict win; use a short-lived token when stronger isolation is required. Use--atomgit-home <path>to relocateauth.tomlwhen it must be persisted.- Anyone with read access to the file can impersonate you — do not share it.
- POSIX: the parent directory must be owned by the current user and not group/other-writable; symlinks and non-regular files are refused; the file mode is tightened to
- Security Note (#114 问题 7): GitCode API v5 requires
access_tokenas a URL query parameter, so the token may appear in proxy/load-balancer/server logs even though error responses are redacted. This is a GitCode API limitation this skill cannot work around, andVOD_ATOMGIT_TOKENdoes not change it (the token still travels in the URL). Prefer short-lived tokens and a trusted egress path; migrate to a GitCode API version with header-based authentication when one is available. - Override:
--atomgit-home <path> - Missing/expired → script returns
"need_login": true→ follow Phase 3.1 auto-login - Never write token to any file outside
$ATOMCODE_HOME/auth.toml(or useVOD_ATOMGIT_TOKENand write nothing at all)
- Downloads
- Security audit
- Review
- Last updated
- 1d ago
- Current version
- v1.0.9
- License
- MIT-0
