数据上报说明
适用产品：Argent 智能体平台（问述科技，运行在客户自有设备上）｜适用版本：2026-10-05 及之后发布的版本（变更记录见 §6）
面向对象：客户、客户的法务/信息安全/采购；可直接作为应答材料提供
联系方式：support@whyshu.com ｜ https://whyshu.com/privacy
一句话
Argent 的诊断上报默认关闭；只有在您明确同意后，才会把“哪台机器、哪一版、 哪条流程、卡在哪一步、什么性质”这类运行元数据发回问述云用于排障，不包含任何业务数据（店铺名、SKU、货件号、订单号、日志全文、截图都不上报），且随时可以关闭。产品只有两条上报通道（运行元数据事件 §2、失败诊断 §2.1），两条共用同一个开关；当前版本不存在任何上报截图、页面内容或日志全文的通道。
§1 默认状态与如何开启/关闭
| 项 | 说明 |
|---|---|
| 默认状态 | 关闭。未同意时不采集、不排队、不发送（也不会“先存着以后补发”） |
| 开启方式一 | 安装时最后一步「诊断上报（可选）」——先列明上报/不上报字段，再由您选择；回车/无终端/CI 一律按不同意处理 |
| 开启方式二 | 打开 Argent → 设置 → Argent → 诊断上报，勾选“开启诊断上报（仅元数据）” |
| 关闭方式 | 同一开关取消勾选即可；也可运行 python3 scripts/telemetry.py --purge 清空本地待发队列 |
| 关闭的即时效果 | 立即停止采集；本地待发队列当场清空；此后不会把关闭期间产生的任何内容补发 |
| 两条通道 | §2 运行元数据事件 与 §2.1 失败诊断上报共用同一个开关：关一次，两条都停（含未开始的采集） |
| 运维排查用硬关 | 环境变量 TELEMETRY_DISABLE=1 为硬关（优先级最高，任何配置都无法覆盖它） |
| 开启的边界 | 只有“在设置页勾选”或在安装时明确同意这两种途径；没有任何环境变量、命令行开关能在未经同意时打开它 |
§1.1 开启前提：本机需持有一枚实例令牌（随许可一并下发）
上报的归属由服务端从本机的凭证里解出（客户端不自报客户名），所以没有任何凭证的机器无法上报：
- 开关只决定“要不要报”；能不能报要求本机持有一枚有效凭证。当前有两种，优先用第一种：
- ① 实例令牌（推荐；随许可下发）——一份由问述科技签发、随机器走的凭证文件 （
~/.dsh/argent/instance-token.json，权限 600）。 它在您装机时与许可文件一并交付，不需要您做任何操作，也不会被上报出去。 默认有效期 365 天，到期前由我们重新签发换发。它与这台机器绑定（安装标识 + 设备摘要； ⛔ 不含原始主机名、不含硬件序列号原文，只存不可逆摘要）。 - ② 账号登录令牌（30 天）——在 Argent「设置 → 账号」登录问述账号后自动写入，作为兜底来源。
- ① 实例令牌（推荐；随许可下发）——一份由问述科技签发、随机器走的凭证文件 （
- 凭证缺失、已过期，或已被我们作废（例如我们轮换签名密钥）时，上报请求会被服务端拒绝（HTTP 401 / 403）； 在本机表现为静默失败 + 长退避（最长每 6 小时一次），
--status里显示凭证来源与lastError。 它不阻断任何业务流程、不刷屏、也不会补发历史数据，但云端收不到这台机器的任何上报（含每日心跳）。 - 日志上报此前要求账号套餐为 Pro / 企业版（否则服务端返回 402）。2026-10-05 起改为「套餐 或 持有有效许可」二者其一——自带模型 Key（BYO）的机器凭有效许可即可上报，不再被套餐挡住。
- 需要恢复上报时：① 先看
python3 scripts/telemetry.py --status（会显示凭证来源类型与到期日，不会显示令牌内容）； ② 凭证缺失/过期 ⇒ 由问述科技重新签发一份换上（随续期一并做，人工一步）； ③ 兜底：在 Argent「设置 → 账号」登录问述账号（令牌自动写入，下一轮自动生效、无需重启）。 - 若您希望该机不上报：保持开关关闭即可——开关是最高闸门，有凭证也不会开启上报（凭证只决定“能不能报”，不决定“要不要报”）。
§2 上报的字段（全部为运行元数据）
| 字段 | 含义 | 举例形态 |
|---|---|---|
| instanceId | 本次安装的随机标识（非硬件指纹、非账号） | 16 位十六进制 |
| hostHash | 主机名的不可逆哈希（不上报原始主机名） | 12 位十六进制 |
| os / arch / profile | 操作系统 / 架构 / 运行配置档 | darwin / arm64 / web |
| version | 程序版本 | 如 1.4.x |
| packVersions | 各能力包的版本 | 如 invoice=1.2.85 |
| capability / flow / role | 哪条业务能力 / 哪条流程 / 哪个角色 | 如 invoice / wenyao-invoice |
| phase | 卡在哪一步 | 如 P4验收 |
| errorClass | 失败性质（分类后的枚举） | 如 needs_agent / retryable |
| attempt / durationSec | 尝试次数 / 耗时（秒） | 数字 |
| caseHash | 单号/票号的哈希（用于把同一张单的多次事件关联起来，不含原文） | 12 位十六进制 |
| detail | 只放分类后的固定措辞的短说明（≤2000 字符，发送前再脱敏一次） | 如“等待选择器超时 #label” |
事件类型只有三种：心跳（每天最多一条，表示“这台机器今天还活着”）、流程失败、引擎失败。
§2.1 失败诊断上报（第 2 条通道，同一个开关）
流程失败时还有一条失败诊断上报（用于“同一类失败在哪台机器、哪一版、哪一步复现”）。 它与 §2 共用同一个开关、同一个默认值（关闭），且只发下面这些字段：
| 字段（服务端字段名） | 含义 | 举例形态 |
|---|---|---|
| failed_step | 卡在哪一步（1–8） | 3 |
| errorClass（error.type） | 失败性质（分类后的枚举） | business / timeout |
| error.message | 分类后的固定措辞（不是原始错误文本） | 如“需人工/运营介入（缺数据或选错行）…” |
| error.recovery_attempted | 已尝试的恢复动作标签（程序内部常量名） | ["check_sku"] |
| error.code | 外部命令返回的错误码 | 1204 |
| error.detail_keys | 本机留了哪几类证据——只报键名，不报值 | ["cli_code","cli_raw"] |
| store / sku / shipment_id / record_id | 店铺名 / SKU / 货件号 / 记录 ID 的 12 位哈希（同店、同票可关联；原文不出本机） | 12 位十六进制 |
| qty / box | 数量 / 箱数（计数，非内容） | 20 / 2 |
| version / ts | 程序版本 / 时间 | — |
该通道不含（代码层面不再构造这些字段）：截图、页面 DOM、日志全文、页面 URL、商品名、 原始错误文本。业务标识只以哈希形式出现；哈希的作用是“把同一次失败关联起来”， 原文只留在您本机的 ~/.dsh/argent/fulfillment-logs/failures.jsonl（供您的技术支持按需查看，不出网）。
历史说明：2026-10-04 及更早版本的这条通道曾携带截图与日志尾部；当前版本已删除该能力， 不是“默认关闭”而是没有这个字段。
§3 明确不上报的内容
- 任何业务数据：店铺名、SKU、货件号、订单号、记录 ID（record_id）、客户名称、商品信息；
- 任何内容全文：日志全文、原始错误文本、页面 DOM、截图、页面 URL、文件内容；
- 原始主机名（只上报上面的 hostHash；哈希的盐保存在您本机、从不出网）；
- 账号与凭据：密码、API Key、令牌（服务端仅按您账号的登录令牌判定归属，客户端不自报客户名）。
三道防线（供技术评审）：① 采集点只传固定措辞，不传原始文本；② 发送前统一脱敏 （令牌/JWT/手机号/6 位以上数字串/URL 参数/邮箱/本机主机名 → 掩码 + 截断）； ③ 服务端对未声明字段一律剥离。
两条通道的开关唯一性（供技术评审）：两条都读同一处配置 （~/.dsh/argent/config.json 的telemetryOptIn）与同一份判定代码；历史遗留的~/.argent-dsh/<profile>/config.yaml 里的telemetry_opt_in 已废弃，产品不读它（即便它写着 true 也不会触发任何上报），可保留或删除，不影响开关。
§4 用途、保留期与存放地
- 用途：① 故障定位（同一类失败在哪台机器、哪一版、哪一步复现）；② 产品改进（能力使用与失败分布统计）。不做广告推送，不出售或共享给第三方（服务商/受托处理方除外，且受同等保密约束）。
- 保留期：90 天，到期滚动删除。
- 存放地：中国境内（腾讯云），不做跨境传输。
- 访问范围：仅问述科技负责该客户的技术支持人员，按账号归属查看。
§5 您本机上的相关文件（可自行查看/删除）
| 路径 | 内容 |
|---|---|
| ~/.dsh/argent/config.json | telemetryOptIn（两条通道的唯一开关）+ telemetryConsent（同意记录：结论/时间/来源） |
| ~/.dsh/argent/instance-token.json | 实例令牌（机器自带凭证，0600）：上报的归属凭证，随许可下发；只用于上报，不含任何业务数据；删掉它只会让本机无法上报，不影响任何业务流程 |
| ~/.dsh/argent/instance.json | 本机实例标识与主机名哈希的盐（0600 权限；主机名原文只在本机） |
| ~/.dsh/argent/telemetry/outbox.jsonl | 本地待发队列（关闭时为空） |
| ~/.dsh/argent/telemetry/state.json | 队列状态与计数（已发/丢弃/清空条数） |
| ~/.dsh/argent/fulfillment-logs/failures.jsonl | 只在本机的失败现场（含截图路径/DOM 摘要/日志路径），不出网；您可自行查看或删除 |
| ~/.argent-dsh/<profile>/config.yaml | 历史遗留文件；其中的 telemetry_opt_in 已废弃（产品不读它，写了 true 也不上报） |
自查命令（只读，不发网）：python3 scripts/telemetry.py --status； 查看“将要发送什么”：python3 scripts/telemetry.py --preview。
§6 变更与联系
- 2026-10-05：① 失败诊断通道收口为纯元数据——删除截图、页面 DOM、日志全文、页面 URL、 商品名与原始错误文本，店名/SKU/货件号/记录 ID 改发 12 位哈希；② 该通道的开关与 §2 统一为同一处配置 + 同一份判定代码，历史遗留键（config.yaml#telemetry_opt_in）废弃、不读。
- 2026-10-05（同日晚些）：③ 开启前提由“需登录问述账号”改为“持有实例令牌（随许可下发）”—— 凭证随机器走、默认 365 天，不再依赖 30 天账号登录令牌（§1.1）；账号令牌仍作兜底来源。 ④ 准入由“账号套餐为 Pro/企业版”改为“套餐 或 持有有效许可”，自带模型 Key（BYO）的机器不再被 402 挡住。 ⑤ 上报字段未新增（hostHash 此前就在上报范围内，本次只是修好服务端未落库的实现缺陷）。
- 本说明随产品实现同步更新；字段范围如有变化，会先在产品内告知。
- 数据与隐私相关请求（查询、删除、关闭、投诉）：support@whyshu.com； 完整隐私政策见 https://whyshu.com/privacy。
本文是面向客户/法务的对外材料，可直接作为应答材料提供。