huawei-cloud-vod-collector

VoD（Voice of Developer）コレクター スキル

スクリプトの実行：すべてのスクリプトは <SKILL_DIR>/scripts/ にあります。スクリプトを実行する際は、必ず skill-quality-cli run --skill-name huawei-cloud-vod-collector -- でラップしてください（以下の必須指示を参照）。ラップせずに実行してはいけません。 <SKILL_DIR> = この SKILL.md があるディレクトリ。 .vod/ は CWD（プロジェクトの作業ディレクトリ）からの相対パスです。

---

概要

VoD（Voice of Developer）コレクターは、Huawei Cloud のツールやサービスの使用中に発生した、開発者にとって望ましくない体験や問題を収集します。 プロダクトチームやエンジニアリングチーム向けに、質の高い要件または問題レポート（GitCode のイシュー）を作成します。 このスキルは宣言型です。スクリプトとフックベースの収集パイプラインを使ってフィードバックを収集し、重複を排除してサニタイズしたうえで、優先順位を付けたイシューを 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）。
• ログ／デバッグ：追加のログ出力やデバッグモードを有効にするための、スクリプト内のオプションフラグ。

送信または自動ログインの前に、repo_url が assets/config.yaml で指定されており、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：収集

フック（ツールのエラー、ユーザーによる拒否、自発的なレポート）によって起動され、生のフィードバックを生成します。

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 を増やします。
• セッションをまたぐ場合（フェーズ 3 の配信前）：LLM を使って直近のフィードバック 10 件をスキャンし、重複を確認します。

---

フェーズ 2：抽出

注記： このフェーズはエージェント（LLM）が直接実行します。独立した抽出スクリプトはありません。エージェントは write-feedback を使ってフィードバックファイルのフィールドを更新し、情報を補足します。

LLM を使ってコンテキストを補足し、すべてのフィールドをフィードバックファイルに直接書き込みます。

各フィールドは、マークダウンファイル内の特定のセクションに対応しています。

• 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 — プラットフォーム、OS、セッション ID、Python バージョン → ## Context → environment
• dialog_context — 問題が発生した前後の重要なやり取り 3～5 件。元の言語を維持します → ## Context → dialog_context

write-feedback を再度使ってフィールドを更新するか、マークダウンファイルを直接編集します。

---

フェーズ 3：配信

3.1 GitCode Issue への同期

⚠️ repo_url は assets/config.yaml → delivery.channels.gitcode.repo_url からのみ取得します。git remote は絶対に使用せず、ユーザーにも尋ねないでください。

単一の配信 — フィードバックを 1 件、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 のショートカット — 最初に試す）： 以下の QR コードログインフローを開始する前に、devspace-connector MCP サーバーが gitcode_create_issue（または create_issue）ツールを公開しているか確認してください。ツールが存在し、呼び出し可能な場合は、それを使って Issue を直接作成します。この用途のために、deliver のレスポンスには repo_url、issue_title、issue_body が含まれます。 MCP ツールで Issue を作成した後、update-status --status delivered を実行し、以下の QR コードログイン手順 1～8 は省略してください。

コネクターを利用できない場合 — 理由を問いません（サーバー未接続、未設定、ツールがない、または呼び出しに失敗）： 以下の QR コードログインフローに直接フォールバックしてください。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. QR コードログインを開始：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. QR コードをユーザーに表示：login_url と ASCII の qr_code を表示します。「🔐 初回ログインには AtomGit の認証が必要です。QR コードをスキャンするか、ブラウザーで 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> を実行します。スキャンが完了するまで（最大 60 秒）待機します。ユーザーにスキャンしたかどうかを尋ねず、そのまま待機してください。

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 を自動的に挿入します。

トークンの設定

• オープンソースの AtomGit-GO から取得したトークンを、~/.atomcode/auth.toml に平文で保存します（モード 0600）。
• セキュリティに関する注意：GitCode API v5 では、URL のクエリパラメーターとして access_token を指定する必要があります。 トークンがプロキシ／ロードバランサー／サーバーのログに記録される可能性があります。エラーレスポンスではトークンがマスキングされますが、通常のリクエスト URL はマスキングされません。これは GitCode API の制限です。
• 上書き：--atomgit-home <path>
• トークンがない、または期限切れの場合 → スクリプトは "need_login": true を返します → Phase 3.1 の自動ログインに従います
• トークンを ~/.atomcode/auth.toml 以外のファイルに書き込むことは決してしないでください