huawei-cloud-vod-collector

VoD（开发者之声）收集器技能

脚本执行：所有脚本都位于 <SKILL_DIR>/scripts/。必须使用 skill-quality-cli run --skill-name huawei-cloud-vod-collector -- 包装每次脚本执行（下文有强制要求）；绝不能直接运行。 <SKILL_DIR> = 包含此 SKILL.md 的目录。 .vod/ 相对于 CWD（项目工作目录）。

---

概述

VoD（开发者之声）收集器用于收集使用 Huawei Cloud 工具或服务时遇到的糟糕开发者体验和问题。 它会为产品和工程团队准备高质量的需求或问题报告（GitCode issue）。 此技能采用声明式设计：通过脚本和基于 hooks 的收集流程收集反馈，对反馈进行去重和清理，并将优先级排序后的问题提交到 GitCode 仓库。

依赖项：质量遥测数据由 skill-quality-cli 自动收集（若未安装，则通过 <SKILL_DIR>/scripts/ensure_cli.sh 安装）。

核心命令

按功能分组的常见 CLI 示例（所有脚本均位于 <SKILL_DIR>/scripts/ 下）：

• 收集

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>

• 提取 / 编辑（使用 write-feedback 更新字段，或直接编辑反馈文件）

• 提交

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 update-status --feedback-id <id> --status delivered --feedbacks-dir .vod/feedbacks

• 自动登录（仅当 deliver 返回 need_login 时）

skill-quality-cli run --skill-name huawei-cloud-vod-collector -- bash <SKILL_DIR>/scripts/vod_install.sh
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>

参数确认

用户或集成方可配置以下参数：

• --feedbacks-dir / --output：反馈存储目录。md_io.py write-feedback 通过 --output 写入；vod_deliver.py（deliver/update-status）通过 --feedbacks-dir 读取。两者默认值均为 .vod/feedbacks/，且接受相同的值（仅命令中的命名不同，含义等同）。
• --atomgit-home / ATOMCODE_HOME：AtomGit-GO 配置目录，默认为 ~/.atomcode。
• delivery.channels.gitcode.repo_url：目标仓库 URL — 仅从 assets/config.yaml 读取。
• capture.dedup_window_sec：会话内去重窗口（秒）。
• storage.max_feedbacks_per_session：每个会话存储的反馈数量上限（默认为 5）。
• 日志记录/调试：脚本中的可选标志，用于启用额外日志记录或调试模式。

提交或自动登录前，请确保已通过 assets/config.yaml 提供 repo_url，且未从 git remote 推断该值。

参考资料

请参阅仓库中的其他实现细节和集成指南：

• references/hooks-setup.md
• references/openclaw-integration.md
• assets/VOD_FEEDBACKS.md
• assets/VOD_ISSUE.md
• references/acceptance-criteria.md
• references/verification-method.md

---

前置条件

Python 依赖项

运行任何脚本前，请先安装所需的 Python 包：

pip install -r <SKILL_DIR>/requirements.txt

---

• skill-quality-cli — 通过 bash <SKILL_DIR>/scripts/ensure_cli.sh 确保已安装（可重复执行；若已存在则跳过）
  • 升级：手动运行 skill-quality-cli upgrade（不会自动升级）
  • 禁用遥测报告：设置 SKILL_QUALITY_REPORT=0

⚠️ 强制要求：此技能中的每次脚本执行都必须使用 skill-quality-cli run --skill-name huawei-cloud-vod-collector -- 包装（例如 skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/md_io.py write-feedback ...）——严禁直接调用 python / md_io.py / vod_sanitize.py / vod_deliver.py / vod_install.* / curl。禁用遥测（选择退出）：SKILL_QUALITY_REPORT=0。引导安装例外：ensure_cli.sh / install_cli.sh 本身是安装程序，因此在尚未安装 skill-quality-cli 时，可以直接（不加包装）执行；CLI 存在后，所有其他脚本执行都必须使用包装命令。

工作流

阶段 1：收集

由 hooks 触发（工具错误、用户拒绝、主动报告），并生成原始反馈。

1.1 生成原始反馈

• 写入反馈文件 — skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/md_io.py write-feedback --output .vod/feedbacks/（查看 --help 了解所有参数）
• 清理敏感信息 — write-feedback 会自动隐藏机密信息。若要手动清理现有文件：skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_sanitize.py file --path <file>

1.2 去重

• 会话内（写入期间）：在 capture.dedup_window_sec 时间范围内，若 session_id + command + error_type 相同，则递增 recurrence_count，而不是写入新文件。
• 跨会话（Phase 3 交付前）：通过 LLM 扫描最近的 10 条反馈，查找重复项。

---

Phase 2：提取

注意： 此阶段由 Agent（LLM）直接执行——没有独立的提取脚本。Agent 使用 write-feedback 更新字段，从而补充反馈文件。

使用 LLM 结合上下文补充反馈，然后将所有字段直接写入反馈文件。

每个字段对应 Markdown 文件中的特定部分：

• error_stack — 从错误上下文中提取回溯信息/退出码 → ## Error Information → error_stack
• user_intent — 用户想做什么（例如“创建 OBS 存储桶”），而不是怎么做 → ## Context → user_intent
• scenario — 还原用户当时正在做什么 → ## User Report → scenario
• expected_behavior — 用户预期的行为。若对话中有明确说明，则据此填写；否则根据错误推断 → ## User Report → expected_behavior
• product_name — 优先级：annotation > agent_action > error_message → 标题前缀 【Product】
• environment — 平台、操作系统、会话 ID、Python 版本 → ## Context → environment
• dialog_context — 问题发生点前后的 3-5 轮关键对话，保留原始语言 → ## Context → dialog_context

再次使用 write-feedback 更新字段，或直接编辑 Markdown 文件。

---

Phase 3：交付

3.1 同步到 GitCode Issue

⚠️ repo_url 仅来自 assets/config.yaml → delivery.channels.gitcode.repo_url。绝不使用 git remote，也绝不询问用户。

单次交付 — 以 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

更新状态 — 将一条反馈标记为已交付（或其他状态）：

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

---

自动登录 — 当 deliver 返回 "need_login": true 时，执行以下操作：

预检查（MCP 快捷方式 — 优先尝试）： 在启动下面的二维码登录流程之前，检查 devspace-connector MCP 服务是否提供 gitcode_create_issue（或 create_issue）工具。如果该工具存在且可调用，则使用它直接创建 Issue — deliver 响应现在会携带 repo_url、issue_title 和 issue_body 以供此用途。MCP 工具创建 Issue 后，运行 update-status --status delivered，并跳过下面的二维码登录步骤 1–8。

如果连接器因任何原因不可用（服务未连接、未配置、缺少工具或调用失败）： 直接回退到下面的二维码登录流程。不要询问用户是否要连接 MCP 服务，也不要提供任何选择 — 静默执行回退流程的步骤 1。任何尝试“启用/连接连接器”的行为都不在此范围内，绝不能作为选项提供。

关键：安装前，必须告知用户：

• 此登录使用开源项目 AtomGit-GO（MIT 许可证）。
• 源码：https://gitcode.com/weixin_45218422/AtomGit-GO

1. 检查并安装：执行 skill-quality-cli run --skill-name huawei-cloud-vod-collector -- bash <SKILL_DIR>/scripts/vod_install.sh（Linux/macOS）或 skill-quality-cli run --skill-name huawei-cloud-vod-collector -- powershell <SKILL_DIR>/scripts/vod_install.ps1（Windows）。

2. 启动服务：skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py server-start → 从 JSON 输出中获取 pid

3. 启动二维码登录：skill-quality-cli run --skill-name huawei-cloud-vod-collector -- 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. 等待授权：skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py login-wait --session-id <session_id> — 阻塞等待扫码（最长 60s）。不要询问用户是否已扫码；只需等待。

6. 收到 SCAN_SUCCESS 后，继续执行步骤 7。

   关键：授权成功后，必须输出安全提示：

   • 安全提示： AtomGit-GO 登录流程仅会将令牌保存到 ${ATOMCODE_HOME:-$HOME/.atomcode}/auth.toml（仅所有者可读，权限模式为 0600）。 任何能够访问此文件的人都可以冒充你 — 请勿分享此文件。
   • 注意： 此文件仅保存在本地 AI Shell 环境中，不会上传到任何外部服务器。
   • 删除： 请手动删除该文件，否则环境资源回收时会清理此文件。

7. 停止服务：skill-quality-cli run --skill-name huawei-cloud-vod-collector -- python <SKILL_DIR>/scripts/vod_deliver.py server-stop --pid <pid>

8. 重新运行原始的 deliver 命令。

---

行为约束

• 取消：仅清理当前文件。绝不删除 .vod/ 或其他记录。
• 拒绝：静默跳过，不要抑制后续触发。
• 验证：仅针对产品／服务问题。内容不得为空或过于简短（如“test”“hello”）。
• 会话限制：最多 storage.max_feedbacks_per_session（默认值为 5）。超出时 → 告知用户。
• 更新：仅原地更新。ID 不可变。状态机：open → delivered → promoted → resolved 或 open → delivered → discarded（delivered 是通过 update-status --status delivered 写入的交付后状态）。
• 自动初始化：首次使用时创建 .vod/。绝不覆盖。
• 质量遥测（强制）：每次脚本／命令执行都必须通过 skill-quality-cli run --skill-name huawei-cloud-vod-collector -- 封装；通过 SKILL_QUALITY_REPORT=0 禁用（选择退出）。

---

存储

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

---

CLI 参考

参数	说明
--atomgit-home <path>	AtomGit-GO 配置目录（默认：~/.atomcode 或 $ATOMCODE_HOME）
--feedback-id <id>	要交付／更新的反馈 ID
--feedbacks-dir <path>	.vod/feedbacks/ 的路径

KooCLI 区域

KooCLI 调用接受全局参数 --cli-region=<region> （例如 hcloud ECS ListServers --cli-region=cn-north-4）。在此技能中，所有 hcloud 调用都通过 scripts/hcloud-run.sh 执行；设置了 HW_CLI_REGION 环境变量时， 该脚本会自动注入 --cli-region（且命令未传入该参数时）。

Token 配置

• Token 来自开源项目 AtomGit-GO，以明文形式保存到 ~/.atomcode/auth.toml（模式 0600）
• **安全提示：**GitCode API v5 要求将 access_token 作为 URL 查询参数。 Token 可能出现在代理／负载均衡器／服务器日志中。错误响应会经过脱敏处理，但正常请求 URL 不会脱敏。这是 GitCode API 的限制。
• 覆盖：--atomgit-home <path>
• 缺失／过期 → 脚本返回 "need_login": true → 按照第 3.1 阶段执行自动登录
• 绝不将 Token 写入 ~/.atomcode/auth.toml 以外的任何文件