feat: add telemetry (agentscope-ai#2)

Author: xieyxclack

README.md

@@ -466,6 +466,25 @@ CoPaw represents both a **Co Personal Agent Workstation** and a "co-paw"—a par
 
 ---
 
+## Telemetry
+
+CoPaw collects **anonymous** usage data during `copaw init` to help us understand our user base and prioritize improvements. Data is sent **once per version** — when you upgrade CoPaw, telemetry is re-collected so we can track version adoption.
+
+**What we collect:**
+
+- CoPaw version (e.g., 0.0.7)
+- Install method (pip, Docker, or desktop app)
+- OS and version (e.g., macOS 14.0, Ubuntu 22.04)
+- Python version (e.g., 3.13)
+- CPU architecture (e.g., x86_64, arm64)
+- GPU availability (yes/no)
+
+**What we do NOT collect:** No personal data, no files, no credentials, no IP addresses, no identifiable information.
+
+When running `copaw init` interactively, you will be asked whether to opt in. If you choose `--defaults`, telemetry is accepted automatically. The prompt appears once per version and never affects CoPaw's functionality.
+
+---
+
 ## License
 
 CoPaw is released under the [Apache License 2.0](LICENSE).

README_ja.md

@@ -465,6 +465,25 @@ CoPawは **Co Personal Agent Workstation**（共同パーソナルエージェ
 
 ---
 
+## テレメトリ
+
+CoPawは `copaw init` 実行時に**匿名**の利用データを収集し、ユーザー環境の把握と製品改善に役立てています。データは**バージョンごとに1回**送信されます — CoPawをアップグレードすると、バージョン分布を把握するために再収集されます。
+
+**収集する情報：**
+
+- CoPawバージョン（例: 0.0.7）
+- インストール方法（pip、Docker、またはデスクトップアプリ）
+- OSとバージョン（例: macOS 14.0、Ubuntu 22.04）
+- Pythonバージョン（例: 3.13）
+- CPUアーキテクチャ（例: x86_64、arm64）
+- GPUの利用可否（はい/いいえ）
+
+**収集しないもの：** 個人データ、ファイル、認証情報、IPアドレス、個人を特定できる情報は一切収集しません。
+
+`copaw init` を対話モードで実行すると、同意するかどうか尋ねられます。`--defaults` モードでは自動的に同意されます。プロンプトはバージョンごとに1回のみ表示され、CoPawの機能には影響しません。
+
+---
+
 ## ライセンス
 
 CoPawは[Apache License 2.0](LICENSE)の下でリリースされています。

README_zh.md

@@ -471,6 +471,25 @@ CoPaw 既是「你的搭档小爪子」（co-paw），也寓意 **Co Personal Ag
 
 ---
 
+## 遥测数据
+
+CoPaw 在执行 `copaw init` 时会收集**匿名**使用数据，帮助我们了解用户环境并优化产品。数据**每个版本收集一次** — 当你升级 CoPaw 后，会重新收集以便我们了解版本分布。
+
+**收集的信息：**
+
+- CoPaw 版本（如 0.0.7）
+- 安装方式（pip、Docker 或桌面应用）
+- 操作系统及版本（如 macOS 14.0、Ubuntu 22.04）
+- Python 版本（如 3.13）
+- CPU 架构（如 x86_64、arm64）
+- GPU 是否可用（是/否）
+
+**不收集：** 不涉及任何个人数据、文件、密钥、IP 地址或可识别信息。
+
+交互式运行 `copaw init` 时，会询问你是否同意。使用 `--defaults` 模式则自动同意。提示每个版本仅出现一次，且不影响 CoPaw 的任何功能。
+
+---
+
 ## 许可证
 
 CoPaw 采用 [Apache License 2.0](LICENSE) 开源协议。

src/copaw/cli/clean_cmd.py

@@ -7,6 +7,7 @@
 import click
 
 from ..constant import WORKING_DIR
+from ..utils.telemetry import TELEMETRY_MARKER_FILE
 
 
 def _iter_children(p: Path) -> list[Path]:
@@ -15,6 +16,7 @@ def _iter_children(p: Path) -> list[Path]:
     return sorted(list(p.iterdir()), key=lambda x: x.name)
 
 
+# pylint: disable=too-many-branches
 @click.command("clean")
 @click.option("--yes", is_flag=True, help="Do not prompt for confirmation")
 @click.option(
@@ -31,14 +33,25 @@ def clean_cmd(yes: bool, dry_run: bool) -> None:
         return
 
     children = _iter_children(wd)
+    # Filter out the telemetry marker file
+    telemetry_marker = wd / TELEMETRY_MARKER_FILE
+    children = [c for c in children if c != telemetry_marker]
+
     if not children:
-        click.echo(f"WORKING_DIR is already empty: {wd}")
+        if telemetry_marker.exists():
+            click.echo(
+                "WORKING_DIR has no removable files",
+            )
+        else:
+            click.echo(f"WORKING_DIR is already empty: {wd}")
         return
 
     click.echo(f"WORKING_DIR: {wd}")
     click.echo("Will remove:")
     for c in children:
         click.echo(f"  - {c}")
+    if telemetry_marker.exists():
+        click.echo(f"Will keep: {TELEMETRY_MARKER_FILE}")
 
     if dry_run:
         click.echo("dry-run: nothing deleted.")

src/copaw/cli/init_cmd.py

@@ -53,6 +53,21 @@
 Review your config and skills regularly; limit tool scope to what you need.
 """
 
+TELEMETRY_INFO = """
+Help improve CoPaw by sharing anonymous usage data!
+
+We collect only:
+• CoPaw version (e.g., 0.0.7)
+• Install method (pip, Docker, or desktop app)
+• OS and version (e.g., macOS 14.0, Ubuntu 22.04)
+• Python version (e.g., 3.11)
+• CPU architecture (e.g., x86_64, arm64)
+• GPU availability (detected, not detailed specs)
+
+No personal data collected! No files, no credentials, no identifiable information.
+This helps us understand CoPaw's usage environment and prioritize improvements.
+"""
+
 
 def _echo_security_warning_box() -> None:
     """Print SECURITY_WARNING in a rich panel with blue border."""
@@ -66,6 +81,18 @@ def _echo_security_warning_box() -> None:
     )
 
 
+def _echo_telemetry_info_box() -> None:
+    """Print TELEMETRY_INFO in a rich panel with blue border."""
+    console = Console()
+    console.print(
+        Panel(
+            TELEMETRY_INFO.strip(),
+            title="[bold]📊 Help improve CoPaw[/bold]",
+            border_style="blue",
+        ),
+    )
+
+
 DEFAULT_HEARTBEAT_MDS = {
     "zh": """# Heartbeat checklist
 - 扫描收件箱紧急邮件
@@ -107,7 +134,11 @@ def _echo_security_warning_box() -> None:
     help="Skip security confirmation (use with --defaults for scripts/Docker).",
 )
 # pylint: disable=too-many-branches,too-many-statements
-def init_cmd(force: bool, use_defaults: bool, accept_security: bool) -> None:
+def init_cmd(
+    force: bool,
+    use_defaults: bool,
+    accept_security: bool,
+) -> None:
     """Create working dir with config.json and HEARTBEAT.md (interactive)."""
     config_path = get_config_path()
     working_dir = config_path.parent
@@ -133,6 +164,26 @@ def init_cmd(force: bool, use_defaults: bool, accept_security: bool) -> None:
             raise click.Abort()
     working_dir.mkdir(parents=True, exist_ok=True)
 
+    # --- Telemetry collection (optional, anonymous) ---
+    from ..utils.telemetry import (
+        collect_and_upload_telemetry,
+        has_telemetry_been_collected,
+        mark_telemetry_collected,
+    )
+
+    if not has_telemetry_been_collected(working_dir):
+        if use_defaults:
+            success = collect_and_upload_telemetry(working_dir)
+
+        else:
+            _echo_telemetry_info_box()
+            if prompt_confirm("Share usage data?", default=True):
+                success = collect_and_upload_telemetry(working_dir)
+                if success:
+                    click.echo("✓ Thank you!")
+            else:
+                mark_telemetry_collected(working_dir)
+
     # --- config.json ---
     write_config = True
     if config_path.is_file() and not force and not use_defaults: