agentic_huge_data_base / wiki
页面 jcode · 15.3 遥测与更新系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / jcode / 15.3

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

代理式研究运行时 · 聚焦本章的模块关系、源码依据与实现要点。

项目jcode 章节15.3 状态全文译文 模块测试、发布与运维、智能体运行时、检索、召回与索引、界面与交互
项目要点页2.5 参考项目 项目章节目录jcode DeepWiki 原始章节Telemetry and Update System 上一章15.2 下一章16
源码线索
  • 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
模块标签
  • 测试、发布与运维
  • 智能体运行时
  • 检索、召回与索引
  • 界面与交互
  • 文档对象与元数据

章节正文

遥测与更新系统

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

遥测与更新系统

相关源文件

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

  • 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。
遥测实现映射图

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

遥测逻辑映射

jcode · 遥测实现映射图 · 图 1
jcode · 遥测实现映射图 · 图 1

来源：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。
更新执行与热执行

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

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

jcode · 更新执行与热执行 · 图 2
jcode · 更新执行与热执行 · 图 2

来源：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