Back to Details

huawei-cloud-vod-collector

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

VoD (Voice of Developer) Collector Skill

VoD（Voice of Developer）Collector Skill

Script execution: All scripts are located in 
<SKILL_DIR>/scripts/
. You must use 
skill action=exec
to execute them. Do not run them directly in a shell. 
<SKILL_DIR>
= directory containing this SKILL.md. 
.vod/
is relative to CWD (project working directory).
脚本执行：所有脚本位于
<SKILL_DIR>/scripts/
目录下。您必须使用
skill action=exec
来执行它们，请勿直接在shell中运行。
<SKILL_DIR>
指包含此SKILL.md的目录。
.vod/
是相对于CWD（项目工作目录）的路径。

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.
VoD（Voice of Developer）收集器用于捕捉开发者使用华为云工具或服务时遇到的不佳体验与问题，为产品和工程团队生成高质量的需求或问题报告（GitCode Issue）。

Core Commands

核心命令

Common CLI examples grouped by function (all scripts under 
<SKILL_DIR>/scripts/
):
  • Capture
bash
python <SKILL_DIR>/scripts/md_io.py write-feedback --output .vod/feedbacks/
python <SKILL_DIR>/scripts/vod_sanitize.py file --path <file>
  • Extract / Edit (use 
    write-feedback
    to update fields or edit feedback files directly)
  • Deliver
bash
python <SKILL_DIR>/scripts/vod_deliver.py deliver --feedback-id <id> --feedbacks-dir .vod/feedbacks
python <SKILL_DIR>/scripts/vod_deliver.py update-status --feedback-id <id> --status delivered --feedbacks-dir .vod/feedbacks
  • Auto-login (only when 
    deliver
    returns 
    need_login
    )
bash
bash <SKILL_DIR>/scripts/vod_install.sh
python <SKILL_DIR>/scripts/vod_deliver.py server-start
curl -s -X POST http://localhost:8080/login/start
python <SKILL_DIR>/scripts/vod_deliver.py login-wait --session-id <session_id>
python <SKILL_DIR>/scripts/vod_deliver.py server-stop --pid <pid>
按功能分组的常见CLI示例（所有脚本均位于
<SKILL_DIR>/scripts/
下）：
  • 捕捉
bash
python <SKILL_DIR>/scripts/md_io.py write-feedback --output .vod/feedbacks/
python <SKILL_DIR>/scripts/vod_sanitize.py file --path <file>
  • 提取/编辑（使用
    write-feedback
    更新字段，或直接编辑反馈文件）
  • 交付
bash
python <SKILL_DIR>/scripts/vod_deliver.py deliver --feedback-id <id> --feedbacks-dir .vod/feedbacks
python <SKILL_DIR>/scripts/vod_deliver.py update-status --feedback-id <id> --status delivered --feedbacks-dir .vod/feedbacks
  • 自动登录（仅在
    deliver
    返回
    need_login
    时使用）
bash
bash <SKILL_DIR>/scripts/vod_install.sh
python <SKILL_DIR>/scripts/vod_deliver.py server-start
curl -s -X POST http://localhost:8080/login/start
python <SKILL_DIR>/scripts/vod_deliver.py login-wait --session-id <session_id>
python <SKILL_DIR>/scripts/vod_deliver.py server-stop --pid <pid>

Parameters

参数配置

The following parameters can be configured by users or integrators:
  • --feedbacks-dir
    : Path for storing feedbacks, default is 
    .vod/feedbacks/
    .
  • --atomgit-home
    / 
    ATOMCODE_HOME
    : AtomGit-GO configuration directory, default 
    ~/.atomcode
    .
  • delivery.channels.gitcode.repo_url
    : Target repository URL — read only from 
    assets/config.yaml.template
    .
  • capture.dedup_window_sec
    : In-session deduplication window in seconds.
  • storage.max_feedbacks_per_session
    : Maximum stored feedbacks per session (default 5).
  • 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.template
and is not inferred from 
git remote
.
用户或集成商可配置以下参数：
  • --feedbacks-dir
    ：存储反馈的路径，默认值为
    .vod/feedbacks/
    。
  • --atomgit-home
    / 
    ATOMCODE_HOME
    ：AtomGit-GO配置目录，默认值为
    ~/.atomcode
    。
  • delivery.channels.gitcode.repo_url
    ：目标仓库URL — 仅从
    assets/config.yaml.template
    读取。
  • capture.dedup_window_sec
    ：会话内去重窗口时长（秒）。
  • storage.max_feedbacks_per_session
    ：每个会话可存储的最大反馈数量（默认值为5）。
  • 日志/调试：脚本内的可选标志，用于启用额外日志或调试模式。
在交付或自动登录前，请确保通过
assets/config.yaml.template
提供
repo_url
，且不要从
git remote
推断该值。

References

参考文档

See additional implementation details and integration guides in the repository:
  • references/hooks-setup.md
  • references/openclaw-integration.md
  • assets/VOD_FEEDBACKS.md
  • assets/VOD_ISSUE.md
  • references/VOD_ISSUE.md
  • references/acceptance-criteria.md
请查看仓库中的额外实现细节与集成指南：
  • references/hooks-setup.md
  • references/openclaw-integration.md
  • assets/VOD_FEEDBACKS.md
  • assets/VOD_ISSUE.md
  • references/VOD_ISSUE.md
  • references/acceptance-criteria.md

Prerequisites

前置条件

Python dependencies

Python依赖

Install required Python packages before running any scripts:
bash
pip install -r <SKILL_DIR>/requirements.txt
运行任何脚本前，请安装所需的Python包：
bash
pip install -r <SKILL_DIR>/requirements.txt

Workflow

工作流程

Phase 1: Capture

阶段1：捕捉

Triggered by hooks (tool errors, user rejection, proactive reports). Generates raw feedback.
由钩子触发（工具错误、用户拒绝、主动报告），生成原始反馈。

1.1 Generate Raw Feedback

1.1 生成原始反馈

  • Write the feedback file — 
    python <SKILL_DIR>/scripts/md_io.py write-feedback --output .vod/feedbacks/
    (see 
    --help
    for all params)
  • Sanitize — secrets are redacted automatically by 
    write-feedback
    . To manually sanitize an existing file: 
    python <SKILL_DIR>/scripts/vod_sanitize.py file --path <file>
  • 写入反馈文件 — 
    python <SKILL_DIR>/scripts/md_io.py write-feedback --output .vod/feedbacks/
    （查看
    --help
    获取所有参数）
  • 清理敏感信息 — 
    write-feedback
    会自动屏蔽敏感信息。如需手动清理现有文件：
    python <SKILL_DIR>/scripts/vod_sanitize.py file --path <file>

1.2 Deduplication

1.2 去重

  • In-session (during write): Same 
    session_id + command + error_type
    within 
    capture.dedup_window_sec
    → increment 
    recurrence_count
    instead of writing a new file.
  • Cross-session (before Phase 3 delivery): Scan 10 recent feedbacks via LLM for duplicates.
  • 会话内去重（写入时）：同一
    session_id + command + error_type
    在
    capture.dedup_window_sec
    时长内重复出现 → 增加
    recurrence_count
    而非创建新文件。
  • 跨会话去重（阶段3交付前）：通过LLM扫描最近10条反馈以识别重复项。

Phase 2: Extract

阶段2：提取

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_stack
  • user_intent
     — What the user wanted to do (e.g. "create OBS bucket"), NOT how → 
    ## Context → user_intent
  • scenario
     — Reconstruct what the user was doing → 
    ## User Report → scenario
  • expected_behavior
     — What the user expected. From dialog if explicit, otherwise infer from error → 
    ## User Report → expected_behavior
  • product_name
     — Priority: annotation > agent_action > error_message → Title prefix 
    【Product】
  • environment
     — Platform, OS, session ID, Python version → 
    ## Context → environment
  • dialog_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.
使用LLM为反馈补充上下文，然后将所有字段直接写入反馈文件。
每个字段对应markdown文件中的特定章节：
  • error_stack
     — 从错误上下文中提取回溯信息/退出码 → 
    ## 错误信息 → error_stack
  • user_intent
     — 用户想要完成的操作（例如"创建OBS存储桶"），而非操作方式 → 
    ## 上下文 → user_intent
  • scenario
     — 还原用户当时的操作场景 → 
    ## 用户报告 → scenario
  • expected_behavior
     — 用户预期的结果。若对话中有明确说明则直接使用，否则从错误信息推断 → 
    ## 用户报告 → expected_behavior
  • product_name
     — 优先级：注解 > agent_action > 错误信息 → 标题前缀
    【产品】
  • environment
     — 平台、操作系统、会话ID、Python版本 → 
    ## 上下文 → environment
  • dialog_context
     — 问题点前后3-5轮关键对话，保留原始语言 → 
    ## 上下文 → dialog_context
可再次使用
write-feedback
更新字段，或直接编辑markdown文件。

Phase 3: Deliver

阶段3：交付

3.1 Sync to GitCode Issue

3.1 同步至GitCode Issue

⚠️ 
repo_url
comes only from 
assets/config.yaml.template
→ 
delivery.channels.gitcode.repo_url
. Never use 
git remote
, never ask the user.
Single delivery — submit one feedback as a GitCode Issue:
bash
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):
bash
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:
CRITICAL: Before installation, MUST tell the user:
  1. Check & install: Execute 
    bash <SKILL_DIR>/scripts/vod_install.sh
    (Linux/macOS) or 
    powershell <SKILL_DIR>/scripts/vod_install.ps1
    (Windows).
  2. Start server: 
    python <SKILL_DIR>/scripts/vod_deliver.py server-start
    → get 
    pid
    from JSON output
  3. Initiate QR login: 
    curl -s -X POST http://localhost:8080/login/start
    → get 
    login_url
    , 
    qr_code
    , 
    session_id
    from JSON
  4. Show QR to user: Display the 
    login_url
    and ASCII 
    qr_code
    . Say: "🔐 First-time login requires AtomGit authorization. Scan the QR code or open the URL in your browser."
  5. Wait for authorization: 
    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.
  6. On 
    SCAN_SUCCESS
    , proceed to step 7.
    CRITICAL: After successful authorization, MUST output the Security Notice:
    • Security Notice: After authorization, the access token will be saved to 
      ~/.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.
  7. Stop server: 
    python <SKILL_DIR>/scripts/vod_deliver.py server-stop --pid <pid>
  8. Re-run the original 
    deliver
    command.
⚠️ 
repo_url
仅来自
assets/config.yaml.template
中的
delivery.channels.gitcode.repo_url
。请勿使用
git remote
获取，也不要询问用户。
单次交付 — 将一条反馈提交为GitCode Issue：
bash
python <SKILL_DIR>/scripts/vod_deliver.py deliver \
  --feedback-id <id> \
  --feedbacks-dir .vod/feedbacks
更新状态 — 将反馈标记为已交付（或其他状态）：
bash
python <SKILL_DIR>/scripts/vod_deliver.py update-status \
  --feedback-id <id> --status delivered --feedbacks-dir .vod/feedbacks
自动登录 — 当
deliver
返回
"need_login": true
时，执行以下步骤：
重要提示：安装前必须告知用户：
  1. 检查并安装：执行
    bash <SKILL_DIR>/scripts/vod_install.sh
    （Linux/macOS）或
    powershell <SKILL_DIR>/scripts/vod_install.ps1
    （Windows）。
  2. 启动服务：
    python <SKILL_DIR>/scripts/vod_deliver.py server-start
    → 从JSON输出中获取
    pid
  3. 初始化二维码登录：
    curl -s -X POST http://localhost:8080/login/start
    → 从JSON输出中获取
    login_url
    、
    qr_code
    、
    session_id
  4. 向用户展示二维码：显示
    login_url
    和ASCII格式的
    qr_code
    ，并告知："🔐首次登录需要AtomGit授权，请扫描二维码或在浏览器中打开该URL。"
  5. 等待授权：
    python <SKILL_DIR>/scripts/vod_deliver.py login-wait --session-id <session_id>
    — 阻塞等待扫描（最长60秒）。请勿询问用户是否已扫描，只需等待。
  6. 收到
    SCAN_SUCCESS
    后，进入步骤7。
    重要提示：授权成功后必须输出安全通知：
    • 安全通知：授权后，访问令牌将被保存至
      ~/.atomcode/auth.toml
      （仅所有者可读，权限为0600）。任何拥有该文件访问权限的人都可以冒充您的身份 — 请勿共享此文件。
    • 说明：令牌仅存储在本地AI Shell环境中，不会上传至任何外部服务器。
    • 删除方式：手动删除该文件，或在环境资源被回收时自动清理。
  7. 停止服务：
    python <SKILL_DIR>/scripts/vod_deliver.py server-stop --pid <pid>
  8. 重新运行原始的
    deliver
    命令。

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").
  • Session limit: Max 
    storage.max_feedbacks_per_session
    (default 5). Exceeded → inform user.
  • Updates: In-place only. ID immutable. State machine: 
    open → promoted → resolved
    or 
    open → discarded
    .
  • Auto-init: 
    .vod/
    created on first use. Never overwritten.
  • 取消操作：仅清理当前文件。禁止删除
    .vod/
    或其他记录。
  • 拒绝请求：静默跳过，不抑制未来的触发。
  • 内容验证：仅处理产品/服务相关问题。拒绝空内容或极简内容（如"test"、"hello"）。
  • 会话限制：最多存储
    storage.max_feedbacks_per_session
    条反馈（默认值为5）。超出时需告知用户。
  • 更新规则：仅允许原地更新。ID不可修改。状态流转：
    open → promoted → resolved
    或 
    open → discarded
    。
  • 自动初始化：首次使用时创建
    .vod/
    目录。禁止覆盖现有目录。

Storage

存储说明

  • Path: 
    <CWD>/.vod/feedbacks/
  • Format: 
    VOD-YYYYMMDD-NNNN.md
  • 路径：
    <CWD>/.vod/feedbacks/
  • 格式：
    VOD-YYYYMMDD-NNNN.md

CLI Reference

CLI参考

ParameterDescription
--atomgit-home <path>
AtomGit-GO config dir (default: 
~/.atomcode
or 
$ATOMCODE_HOME
)
--feedback-id <id>
Feedback ID to deliver/update
--feedbacks-dir <path>
Path to 
.vod/feedbacks/
参数描述
--atomgit-home <path>
AtomGit-GO配置目录（默认值：
~/.atomcode
或
$ATOMCODE_HOME
）
--feedback-id <id>
需交付/更新的反馈ID
--feedbacks-dir <path>
.vod/feedbacks/
的路径

Token Configuration

令牌配置

  • Token from open-source AtomGit-GO, saved in plaintext to 
    ~/.atomcode/auth.toml
    (mode 
    0600
    )
  • 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/auth.toml
  • 令牌来自开源项目AtomGit-GO，以明文形式保存至
    ~/.atomcode/auth.toml
    （权限为
    0600
    ）
  • 覆盖方式：使用
    --atomgit-home <path>
    参数
  • 令牌缺失/过期 → 脚本返回
    "need_login": true
    → 执行阶段3.1的自动登录流程
  • 禁止将令牌写入
    ~/.atomcode/auth.toml
    以外的任何文件