15.3 · 遥测与更新系统（Telemetry and Update System）

遥测与更新系统（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/1jehuang/jcode/15.3-telemetry-and-update-system

翻译时间：2026-05-27T08:45:27.114Z

翻译模型：deepseek-chat

原文字符数：8034

项目：jcode (jcode)

---

遥测与更新系统

相关源文件

以下文件为本维基页面的生成提供了上下文：

• TELEMETRY.md
• crates/jcode-update-core/Cargo.toml
• crates/jcode-update-core/src/lib.rs
• src/telemetry.rs
• src/telemetry/lifecycle.rs
• src/telemetry/tests.rs
• src/telemetry_state.rs
• src/telemetry_tests.rs
• src/update.rs
• telemetry-worker/README.md
• telemetry-worker/health.sql
• telemetry-worker/migrations/0007_dashboard_indexes.sql
• telemetry-worker/migrations/0008_agent_time_and_churn.sql
• telemetry-worker/package.json
• telemetry-worker/schema.sql
• telemetry-worker/src/worker.js

遥测与更新系统为 jcode 生态提供匿名使用洞察和自动化二进制文件维护。遥测系统采用隐私优先的设计理念，使用基于 Cloudflare Worker 的入库管线以及本地退出机制。更新系统负责管理 jcode 二进制文件的生命周期，同时支持基于 GitHub Release 的稳定版更新和基于源码的开发版构建。

遥测系统

遥测系统跟踪高层级的使用模式和错误率，以提升系统稳定性。该系统在 src/telemetry.rs 中实现，并与远程的 Cloudflare Worker 端点进行通信。

事件类型与数据流

遥测事件分为几种主要类型，在 jcode-usage-types 中定义为可序列化的结构体：

1. 安装事件：在首次启动时触发一次，用于捕获环境元数据（操作系统、架构、版本）src/telemetry.rs:5-13。
2. 会话开始事件：在新会话开始时发送，包含初始提供商、模型以及会话是否被恢复等信息 src/telemetry.rs:93-187。
3. 轮次结束事件：跟踪每轮次的指标，包括 Token 数量、工具使用情况和延迟 src/telemetry.rs:39-90。
4. 会话生命周期事件（结束/崩溃）：在退出或崩溃时发送，包含详细指标，如持续时间、轮次数、工具成功率、Token 使用量和传输方式 src/telemetry.rs:14-17。
5. 引导与反馈事件：跟踪粗略的漏斗步骤和明确的用户情感（点赞/点踩）src/telemetry.rs:5-13。

遥测实现映射图

下图将自然语言概念映射到遥测子系统中的具体代码实体。

遥测逻辑映射

graph TD
    subgraph "自然语言空间"
        A["隐私控制"]
        B["事件入库"]
        C["指标跟踪"]
        D["身份管理"]
    end

    subgraph "代码实体空间"
        A --> E["is_enabled()"]
        E --> F["JCODE_NO_TELEMETRY / DO_NOT_TRACK"]
        B --> G["emit_lifecycle_event()"]
        G --> H["TELEMETRY_ENDPOINT"]
        C --> I["SessionTelemetry"]
        C --> J["TurnTelemetry"]
        C --> K["ERROR_PROVIDER_TIMEOUT / ERROR_RATE_LIMITED"]
        D --> L["get_or_create_id()"]
        L --> M["storage::jcode_dir() / telemetry_id"]
    end

来源：src/telemetry.rs:23-37、src/telemetry.rs:93-187、src/telemetry/state_support.rs:1-20、TELEMETRY.md:1-7

退出机制与隐私保护

用户可以通过以下几种方式退出遥测：

• 环境变量：设置 JCODE_NO_TELEMETRY 或 DO_NOT_TRACK src/telemetry_tests.rs:13-27。
• 本地文件：在 ~/.jcode/ 目录下创建一个名为 no_telemetry 的文件。
• TELEMETRY.md：文档中明确列出了所有收集的字段，以确保透明度 TELEMETRY.md:9-126。

Cloudflare Worker 入库

遥测后端是一个 Cloudflare Worker，它将事件存储在 D1 SQL 数据库中。该 Worker 在 /v1/event 端点接收 JSON 载荷，并将其映射到 events 表模式 telemetry-worker/src/worker.js:17-45。

类别	关键跟踪指标
错误	error_provider_timeout、error_rate_limited、error_auth_failed src/telemetry.rs:31-35
功能	feature_memory_used、feature_swarm_used、feature_mcp_used src/telemetry.rs:124-133
工具	tool_cat_read_search、tool_cat_write、tool_cat_shell src/telemetry.rs:156-167
传输方式	transport_https、transport_persistent_ws_reuse src/telemetry.rs:135-140

来源：src/telemetry.rs:93-187、telemetry-worker/schema.sql:3-119、telemetry-worker/src/worker.js:179-204

---

更新系统

更新系统负责发现、下载和安装新的 jcode 版本。它支持多个渠道：稳定版（GitHub Releases）和源码构建版（本地 git 检出）。

PreparedUpdate 生命周期

更新过程通过 PreparedUpdate 枚举进行管理，该枚举表示检测到的更新的状态 crates/jcode-update-core/src/lib.rs:47-59。

1. 检查：如果距离上次检查的时间超过了 UPDATE_CHECK_INTERVAL（60 秒），系统会检查更新 src/update.rs:20、src/update.rs:112-118。
2. 估算：UpdateEstimate 根据历史数据（存储在 UpdateMetadata 中）或资源大小来计算预期持续时间 crates/jcode-update-core/src/lib.rs:18-22、crates/jcode-update-core/src/lib.rs:86-124。
3. 后台阈值：如果更新预计耗时超过 BACKGROUND_UPDATE_THRESHOLD（15 秒），则会被标记为 should_background crates/jcode-update-core/src/lib.rs:8、crates/jcode-update-core/src/lib.rs:130。
4. GitHub Release：稳定版更新从 1jehuang/jcode 获取元数据 src/update.rs:19，并解析 GitHubRelease 和 GitHubAsset 结构体 src/update.rs:198-225。

更新执行与热执行

当触发更新时，系统会执行"热"切换到新二进制文件。

二进制文件更新与执行流程

graph TD
    subgraph "更新逻辑 (src/update.rs)"
        CHECK["UpdateMetadata::should_check()"]
        PREP["PreparedUpdate"]
        FETCH["fetch_latest_release_blocking()"]
        META["update_metadata.json"]
    end

    subgraph "热执行逻辑"
        HU["hot_update()"]
        HRB["hot_rebuild()"]
        RP["platform::replace_process()"]
    end

    subgraph "二进制文件管理"
        EXE["std::env::current_exe()"]
        CAND["preferred_reload_candidate()"]
    end

    CHECK --> FETCH
    FETCH --> PREP
    PREP --> HU
    HU --> RP
    HRB --> RP
    RP --> EXE

来源：src/update.rs:112-118、src/update.rs:198-225、crates/jcode-update-core/src/lib.rs:47-59

关键函数与结构体

• UpdateMetadata：持久化存储上次检查时间、已安装版本以及发布版与源码版更新的历史持续时间 src/update.rs:69-77。
• should_auto_update：判断是否应进行自动更新的逻辑，会检查发布版构建状态和 git 仓库是否存在 src/update.rs:146-162。
• verify_asset_checksum_text：通过比对 SHA256SUMS 来确保下载的二进制文件完整性 crates/jcode-update-core/src/lib.rs:245-255。
• is_release_build：判断当前二进制文件是否使用 JCODE_RELEASE_BUILD 标志构建，以决定走发布版还是源码版更新路径 src/update.rs:60-62。

平台抽象

更新系统依赖 src/update.rs 和 jcode-update-core 来实现平台特定的资源命名和 git 协调 crates/jcode-update-core/src/lib.rs:134-170。对于源码版更新，它使用 git pull --ff-only 来防止分支分歧问题 src/update.rs:164-180。

来源：src/update.rs:1-122、crates/jcode-update-core/src/lib.rs:1-255