@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/telemetry.py

@@ -0,0 +1,873 @@
+#!/usr/bin/env python3
+"""遥测上报（日志上报）—— 客户机侧：**元数据事件**的采集、脱敏、排队、上报。
+
+## 设计口径（2026-09-21 用户裁定；2026-10-04 合规改造 = 形态 A「告知—同意」）
+- **默认关（opt-in）**：`config.json#telemetryOptIn` **无键 = 不开**。开启只有两条路 ——
+  ① 安装期在**明确告知字段范围**后由用户点同意（`install-argent.mjs` 的「诊断上报（可选）」步）；
+  ② 设置页「诊断上报」开关。`TELEMETRY_DISABLE=1` 是**硬关**（优先级最高）。
+  ⛔ **没有任何环境变量能"打开"它** —— 打开必须在 `config.json` 留下显式同意记录。
+- **不补发**：关闭期间**不采集、不堆积、不补发**。队列按**采集时刻的同意标记**过滤
+  （`consent='optin-v1'`）：升级前（"默认开"时代）产生的事件**不带标记** ⇒ 被剔除、永不外发；
+  且关闭状态下 `flush` 会直接清空本地队列。**开启期间**产生的失败事件，退避重试语义不变。
+- **只上报元数据**：哪台机器（`instanceId` + 主机名**哈希** `hostHash`）、哪一版
+  （version/能力包版本）、哪条流程、卡在哪一步（phase）、什么性质（errorClass）、耗时/尝试次数。
+  **店铺名 / SKU / 货件号 / 截图 / 日志全文 / 原始主机名一律不上报** —— 主防线在这里（服务端
+  `additionalProperties:false` 只是兜底，而且是"静默剥离"不是报错）。
+- **归属由服务端决定**：客户端**不自报客户名**。服务端从登录令牌解出 `userId`
+  （令牌取自 `~/.dsh/argent/config.json` 的 `apiKey`），所以客户端伪造不了归属。
+- **绝不阻断主流程**：任何失败都静默（写 `state.json` 的失败计数），调用方拿到的永远是 0。
+- **不联网也照跑**：事件先落本地 outbox（追加写 + flock），由触发链每轮 `--flush` 一次；
+  断网/服务端不可用时按退避重试，outbox 有容量上限（超了丢最旧并计数）。
+- **透明**：`--preview` 能打印"将要发什么"；`--status` 打印队列与最近结果。
+
+## 幂等
+每条事件带 `eventId`（uuid）。上报成功才把它移出 outbox；若"发出去了但没收到响应"，
+下次重试带**同一个 eventId**，服务端按 (userId, eventId) 去重 ⇒ 不会产生重复行。
+
+用法：
+    python3 scripts/telemetry.py --init-instance
+    python3 scripts/telemetry.py --emit --kind failure --capability invoice \\
+        --flow wenyao-invoice --phase P4验收 --error-class needs_agent --case wenyao-invoice__76636923 \\
+        --detail '等待选择器超时 #label'
+    python3 scripts/telemetry.py --heartbeat --flush
+    python3 scripts/telemetry.py --flush [--max 20]
+    python3 scripts/telemetry.py --preview
+    python3 scripts/telemetry.py --status
+    python3 scripts/telemetry.py --purge          # 清空本地队列（关闭上报/撤回同意时用）
+环境变量：ARGENT_DATA_DIR（数据目录）、WHYSHU_API_URL（上报地址覆盖，测试用）、
+        TELEMETRY_DISABLE=1（**硬关**；注意：没有任何环境变量能"打开"上报）
+退出码：恒 0（除显式用法错误 2）；本模块不允许因为遥测失败而影响调用方。
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import datetime as dt
+import hashlib
+import json
+import os
+import pathlib
+import platform
+import re
+import socket
+import sys
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+# 跨平台文件锁**唯一真源**（POSIX `fcntl.flock` / Windows `msvcrt.locking`）：
+# 此前本文件顶层 `import fcntl` ⇒ Windows 上 `ModuleNotFoundError` ⇒ 遥测整个不可用。
+from argent_filelock import best_effort      # noqa: E402
+
+try:
+    from flow_registry import consumer_doc as _registry_doc
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else pathlib.Path(__file__).resolve().with_name("flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+REPO = HERE.parent
+
+# ── 路径与上限 ────────────────────────────────────────────────────────────────
+OUTBOX_MAX_EVENTS = 1000
+OUTBOX_MAX_BYTES = 5 * 1024 * 1024
+DETAIL_MAX = 2000                 # 与 服务端 TELEMETRY_DETAIL_MAX 同口径
+SENT_RING = 500                   # 已发 id 的环形记录（仅用于自检/去重观察）
+HTTP_TIMEOUT = 8
+BACKOFF_BASE_SEC = 300            # 5 分钟起
+BACKOFF_MAX_SEC = 6 * 3600        # 最长 6 小时
+GONE_CODES = (401, 402, 404, 405, 501)   # 未登录 / 未订阅 / 端点尚未部署 ⇒ 长退避，不刷屏
+EVENT_KINDS = ('heartbeat', 'failure', 'engine')
+ENDPOINT = '/api/argent/telemetry/event'
+# ── 同意标记（合规形态 A：告知—同意）──────────────────────────────────────────
+# 每条事件在**采集时刻**打上标记，`flush` 只发带标记的。作用有两个：
+#   ① 迁移语义：升级前（"默认开"时代）产生、还压在 outbox 里的事件**不带标记** ⇒ 被剔除、永不外发
+#      （客户在"关闭/未同意"状态下产生的东西，不能在开启后补发出去）；
+#   ② 撤回语义：标记是采集时刻的事实，之后的开关变化不会把旧事件"洗白"。
+# ⚠️ 这个键**只在本地**：`_post()` 会把它从 HTTP 载荷里剔除（服务端字段契约一个字都不变）。
+CONSENT_TAG = 'optin-v1'
+HOST_HASH_LEN = 12
+
+
+def data_dir() -> pathlib.Path:
+    """数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链，与 JS 内核同语义）。"""
+    return pathlib.Path(resolve_data_dir()['dir'])
+
+
+def tel_dir() -> pathlib.Path:
+    return data_dir() / 'telemetry'
+
+
+def outbox_path() -> pathlib.Path:
+    return tel_dir() / 'outbox.jsonl'
+
+
+def state_path() -> pathlib.Path:
+    return tel_dir() / 'state.json'
+
+
+def sent_path() -> pathlib.Path:
+    return tel_dir() / 'sent-ids.jsonl'
+
+
+def instance_path() -> pathlib.Path:
+    return data_dir() / 'instance.json'
+
+
+def api_base() -> str:
+    raw = os.environ.get('WHYSHU_API_URL') or ''
+    if raw:
+        return raw.rstrip('/')
+    try:
+        cfg = json.loads((data_dir() / 'config.json').read_text(encoding='utf-8'))
+        base = str(cfg.get('apiBase') or '').strip()
+        if base:
+            return base.rstrip('/')
+    except Exception:  # noqa: BLE001
+        pass
+    return 'https://whyshu.com'
+
+
+def auth_token() -> str:
+    """登录令牌：当前配置面 config.json 的 apiKey（服务端用它解出 userId）。"""
+    token = os.environ.get('WHYSHU_API_KEY') or ''
+    if token:
+        return token.strip()
+    try:
+        cfg = json.loads((data_dir() / 'config.json').read_text(encoding='utf-8'))
+        return str(cfg.get('apiKey') or '').strip()
+    except Exception:  # noqa: BLE001
+        return ''
+
+
+# ── 凭证：**实例令牌优先，账号令牌兜底**（2026-10-05 路线 B「机器自带凭证」）──────
+# 背景：客户机是"一直开着、没人登录"的，账号 JWT 只有 30 天且在服务端轮换密钥时全灭
+# （2026-09-14 实况）⇒ 交付一台机器时应交付**随机器走**的凭证。
+# 形态与契约（唯一权威 = whyshu-svr/docs/ops/instance-token.md）：
+#   文件  <数据目录>/instance-token.json（0600）—— 安装器从许可同一条离线下发链路写入；
+#   头    x-instance-token: <紧凑串 it1.<b64url(payload)>.<sig)>（与服务端 middleware/instanceAuth.js 同口径）
+#   加固  x-instance-device: <64hex 设备码>（取自本机 license.json#device.code；服务端比对令牌里的 deviceCode）
+# ⛔ **fail-closed**：没有令牌 ⇒ 不发（`no-token`），**绝不**匿名上报、绝不崩。
+# ⛔ 令牌串**只进 HTTP 头**，不进日志、不进 state.json、`--status` 只显示"来源类型"。
+INSTANCE_TOKEN_FILE = 'instance-token.json'
+INSTANCE_TOKEN_HEADER = 'x-instance-token'
+INSTANCE_DEVICE_HEADER = 'x-instance-device'
+INSTANCE_TOKEN_ENV = 'ARGENT_INSTANCE_TOKEN'
+
+
+def instance_token_path() -> pathlib.Path:
+    return data_dir() / INSTANCE_TOKEN_FILE
+
+
+def _decode_token_payload(token: str) -> dict:
+    """紧凑串 → 载荷（**只解码、不验签**：客户端没有签名密钥，判真伪是服务端的事）。
+
+    解码只为两件事：① 本地 fail-closed 自检（instanceId 是否是本机的）；② `--status` 回显
+    到期日与来源类型。任何异常 ⇒ 空 dict（绝不因为"看不懂令牌"而抛出去）。
+    """
+    try:
+        parts = str(token or '').split('.')
+        if len(parts) != 3:
+            return {}
+        pad = '=' * (-len(parts[1]) % 4)
+        raw = base64.urlsafe_b64decode(parts[1] + pad)
+        obj = json.loads(raw.decode('utf-8'))
+        return obj if isinstance(obj, dict) else {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def local_device_code() -> str:
+    """本机设备码：取自已安装的 `license.json#device.code`（64hex）。
+
+    为什么从许可文件取而不是自己跑 `ioreg`：那个值**就是签发侧用的那个**（令牌与许可一起下发），
+    两边必然一致；自己再算一遍只会在算法/夹具上引入新的分叉点。
+    读不到 ⇒ 空串（服务端对"没带设备头"按加固层放行，见中间件注释）。
+    """
+    try:
+        lic = json.loads((data_dir() / 'license.json').read_text(encoding='utf-8'))
+        code = str(((lic or {}).get('device') or {}).get('code') or '').strip().lower()
+        return code if re.fullmatch(r'[0-9a-f]{64}', code) else ''
+    except Exception:  # noqa: BLE001
+        return ''
+
+
+def instance_token() -> dict:
+    """读实例令牌。**只读一个键**（`token`）：文件允许带便于人工核对的元数据，但不参与鉴权。
+
+    返回 `{token, source, payload, instanceId, deviceCode, exp, error}`；没有 ⇒ token 为空。
+    优先级：环境变量 `ARGENT_INSTANCE_TOKEN`（运维/测试覆盖）→ `<数据目录>/instance-token.json`。
+    """
+    out = {'token': '', 'source': '', 'payload': {}, 'instanceId': '', 'deviceCode': '', 'exp': '', 'error': ''}
+    raw = (os.environ.get(INSTANCE_TOKEN_ENV) or '').strip()
+    src = f'env:{INSTANCE_TOKEN_ENV}'
+    if not raw:
+        p = instance_token_path()
+        try:
+            raw = p.read_text(encoding='utf-8').strip()
+            src = f'file:{p}'
+        except Exception:  # noqa: BLE001
+            return out
+    if not raw:
+        return out
+    token = raw
+    if raw.startswith('{'):                       # JSON 信封（安装器写入的正常形态）
+        try:
+            doc = json.loads(raw)
+            token = str((doc or {}).get('token') or '').strip()
+        except Exception:  # noqa: BLE001
+            out['error'] = 'unparsable-json'
+            return out
+    if not token:
+        out['error'] = 'empty-token'
+        return out
+    payload = _decode_token_payload(token)
+    if not payload:
+        out['error'] = 'undecodable-token'
+    out.update({'token': token, 'source': src, 'payload': payload,
+                'instanceId': str(payload.get('instanceId') or ''),
+                'deviceCode': str(payload.get('deviceCode') or '').lower(),
+                'exp': str(payload.get('exp') or '')})
+    return out
+
+
+def account_token() -> str:
+    """账号登录令牌（兜底来源）：env `WHYSHU_API_KEY` → `config.json#apiKey`。"""
+    return auth_token()
+
+
+def credential() -> dict:
+    """**当前生效的凭证**（唯一判定点）：实例令牌优先，账号令牌兜底。
+
+    返回 `{kind, token, source, headers, note}`：
+      · `kind='instance'` ⇒ 只发 `x-instance-token`（+ 可能的 `x-instance-device`）；**不发** Bearer；
+      · `kind='account'`  ⇒ 老路径 `Authorization: Bearer <账号 JWT>`（逐字节不变，向后兼容）；
+      · `kind='none'`     ⇒ fail-closed：不发（`no-token`）。
+    ⛔ 返回的 `token` 只许进 HTTP 头；调用方**不得**打印/落盘（`--status` 只看 kind/source）。
+    """
+    inst = instance_token()
+    if inst['token'] and not inst['error']:
+        # 本地自检：令牌是**发给这台机器**的吗？（instanceId 不匹配 ⇒ 绝不发网，本地就停，
+        # 否则会变成"服务端 403 + 长退避"的静默故障；故障点在这里更可诊断）
+        me = str(ensure_instance().get('installId') or '')
+        if inst['instanceId'] and me and inst['instanceId'] != me:
+            return {'kind': 'none', 'token': '', 'source': inst['source'], 'headers': {},
+                    'note': f'instance-token-mismatch（令牌是给 {inst["instanceId"]} 的，本机是 {me}）'}
+        headers = {INSTANCE_TOKEN_HEADER: inst['token']}
+        dev = local_device_code() or inst['deviceCode']
+        if dev:
+            headers[INSTANCE_DEVICE_HEADER] = dev
+        return {'kind': 'instance', 'token': inst['token'], 'source': inst['source'],
+                'headers': headers, 'note': ''}
+    acct = account_token()
+    if acct:
+        return {'kind': 'account', 'token': acct, 'source': 'account-jwt', 'headers': {},
+                'note': ('instance-token 不可用（' + inst['error'] + '）⇒ 回落账号令牌'
+                         if inst['error'] else '')}
+    return {'kind': 'none', 'token': '', 'source': inst['source'] if inst['error'] else '',
+            'headers': {}, 'note': ('instance-token 不可用（' + inst['error'] + '）' if inst['error'] else '')}
+
+
+def _config_opt_in() -> bool:
+    """读 `config.json#telemetryOptIn`：**显式为真才算开**（无键/缺文件/false/读坏 ⇒ 一律不开）。"""
+    try:
+        cfg = json.loads((data_dir() / 'config.json').read_text(encoding='utf-8'))
+    except Exception:  # noqa: BLE001
+        return False
+    v = cfg.get('telemetryOptIn')
+    if v is True:
+        return True
+    return str(v).strip().lower() in ('true', '1', 'yes')
+
+
+def telemetry_enabled() -> bool:
+    """**默认关（opt-in）**：只有 `config.json#telemetryOptIn` 显式为真才开。
+
+    优先级：`TELEMETRY_DISABLE=1` ⇒ **硬关**（最高，压过一切）> `telemetryOptIn`。
+    ⛔ 没有任何环境变量能**打开**上报 —— 打开只有"留下显式同意记录"这一条路
+    （安装期的「诊断上报（可选）」步，或设置页的「诊断上报」开关）。
+    """
+    if os.environ.get('TELEMETRY_DISABLE') in ('1', 'true', 'yes'):
+        return False
+    return _config_opt_in()
+
+
+def host_hash(host: str = '', salt: str = '') -> str:
+    """主机名 → **不可逆**短哈希（12 hex，同机同盐恒等 ⇒ 可去重、可分组）。
+
+    为什么不是明文：原始 hostname 常含用户名/机器名（如 `huangwei-mac-mini.local`），是
+    最容易指向具体个人/设备的字段。盐 = **本机随机值**（`instance.json#hostSalt`，0600），
+    **只存本地、从不出网** ⇒ 云端拿到哈希连字典攻击的对象都没有。
+    代价（写清楚）：**重装/换机会换盐 ⇒ 哈希会变**；跨安装去重请用 `instanceId`
+    （它本来就是"每安装唯一"，语义正好）。
+    """
+    if not host:
+        return ''
+    return hashlib.sha256(f'{salt}|{host}'.encode('utf-8')).hexdigest()[:HOST_HASH_LEN]
+
+
+# ── 机器身份（instance.json）──────────────────────────────────────────────────
+def ensure_instance() -> dict:
+    """读取/创建实例身份。同一个客户两台机器、或同机两个 profile 都能分开。
+
+    ⚠️ 2026-10-04（合规）：`host`（原始主机名）**只留本地**（本机自检/排障看），
+    上报走 `hostHash` —— 盐 `hostSalt` 是**本机随机值、从不出网**，老实例会在首次读取时补种
+    （就地补齐，不重建 installId）。
+    """
+    p = instance_path()
+    d = None
+    try:
+        d = json.loads(p.read_text(encoding='utf-8'))
+    except Exception:  # noqa: BLE001
+        d = None
+    if not isinstance(d, dict) or not d.get('installId'):
+        d = {
+            'installId': uuid.uuid4().hex[:16],
+            'createdAt': dt.datetime.now().isoformat(timespec='seconds'),
+            'host': socket.gethostname()[:64],
+            'os': platform.system().lower()[:32],
+            'arch': platform.machine()[:32],
+        }
+    changed = False
+    if not d.get('hostSalt'):
+        d['hostSalt'] = uuid.uuid4().hex          # 本机随机盐：**永不出网**（见 host_hash）
+        changed = True
+    host = str(d.get('host') or socket.gethostname())
+    if not d.get('hostHash') or d.get('hostHashSalt') != d.get('hostSalt'):
+        d['hostHash'] = host_hash(host, str(d.get('hostSalt') or ''))
+        d['hostHashSalt'] = d['hostSalt']         # 记录"这个哈希是哪个盐算的"（换盐必重算）
+        changed = True
+    if changed:
+        try:
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text(json.dumps(d, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+            os.chmod(p, 0o600)
+        except Exception:  # noqa: BLE001
+            pass
+    return d
+
+
+_CAP_MAP: dict | None = None
+
+
+def capability_of(flow: str) -> str:
+    """流程 → 能力（读注册表一次并缓存；读不到就空）。"""
+    global _CAP_MAP
+    if _CAP_MAP is None:
+        _CAP_MAP = {}
+        try:
+            doc = _registry_doc()
+            for fid, spec in (doc.get('flows') or {}).items():
+                _CAP_MAP[str(fid)] = str((spec or {}).get('capability') or '')
+        except Exception:  # noqa: BLE001
+            pass
+    return _CAP_MAP.get(str(flow or ''), '')
+
+
+def flow_of_case(case_id: str) -> str:
+    """票号 → 流程 id（caseId 形如 `<flow>__<票>`）。"""
+    cid = str(case_id or '')
+    return cid.split('__', 1)[0] if '__' in cid else ''
+
+
+# 引擎级失败的"合成票号"（不是真实货物票）：这类由**触发链**发 kind=engine，
+# 台账钩子要跳过，否则同一次失败会产生两条事件（一条 failure + 一条 engine）。
+ENGINE_CASE_PREFIXES = ('claim__', 'preflight__', 'invoice-ready-leftover__')
+
+
+def is_engine_case(case_id: str) -> bool:
+    return str(case_id or '').startswith(ENGINE_CASE_PREFIXES)
+
+
+def repo_version() -> str:
+    try:
+        return (REPO / 'VERSION').read_text(encoding='utf-8').strip()
+    except Exception:  # noqa: BLE001
+        return ''
+
+
+def pack_versions() -> dict:
+    """能力包版本（决定"他那版还有没有这个 bug"）。读锁文件，读不到就空。"""
+    try:
+        lock = json.loads((HERE / 'capability-packs.lock.json').read_text(encoding='utf-8'))
+        return {k: str((v or {}).get('version') or '') for k, v in (lock.get('capabilities') or {}).items()}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+# ── 脱敏（**这是主防线**：日志/错误文本里什么都可能有）──────────────────────
+_SENSITIVE = (
+    # 令牌/密钥类（与 orchestrator 的同口径，另加 URL 里的 query）
+    (re.compile(r'(?i)((?:tenant_|user_)?access_token|app_?secret|client_secret|password|passwd|'
+                r'authorization|cookie|api[_-]?key)("?\s*[:=]\s*"?)([A-Za-z0-9_\-\.]{6,})'), r'\1\2***'),
+    (re.compile(r'(?i)(--[a-z-]*(?:token|secret|key|pass)\s+)(\S+)'), r'\1***'),
+    (re.compile(r'(?i)\b(bearer|basic)\s+[A-Za-z0-9._\-+/=]{8,}'), r'\1 ***'),
+    # JWT（eyJ...）与常见的 40+ 长十六进制/Base64 串
+    (re.compile(r'\beyJ[A-Za-z0-9._\-]{20,}'), 'JWT***'),
+    (re.compile(r'\b[A-Fa-f0-9]{40,}\b'), 'HEX***'),
+    # 手机号 / 长数字（货件号、订单号、record_id 之类）
+    (re.compile(r'(?<!\d)1[3-9]\d{9}(?!\d)'), 'PHONE***'),
+    # 6 位起就掩（实测：货件号 76636923 是 8 位，用 10 位规则会漏）
+    (re.compile(r'(?<!\d)\d{6,}(?!\d)'), 'NUM***'),
+    # 邮箱 / URL query（query 里常带 token 或业务参数）
+    (re.compile(r'\b[\w.+-]+@[\w-]+\.[\w.]{2,}\b'), 'MAIL***'),
+    (re.compile(r'(https?://[^\s?]+)\?[^\s]*'), r'\1?***'),
+)
+
+
+def _host_variants() -> list:
+    """本机主机名的**全部写法**（含短名/去 `.local`），用于把 detail 里的明文主机名掩掉。
+
+    为什么要在 redact 里补这一条（2026-10-04 合规）：字段面已经改成 `hostHash` 了，但
+    `detail` 是自由文本 —— 历史调用点就写过 `detail=f'host={socket.gethostname()}'`，
+    类似形态（`--detail` 手敲、异常文本里带 host）随时会再出现 ⇒ **字段面 + 文本面**两道都要堵。
+    """
+    out = []
+    try:
+        h = socket.gethostname() or ''
+    except Exception:  # noqa: BLE001
+        h = ''
+    for cand in (h, h.split('.')[0] if '.' in h else '', h[:-len('.local')] if h.endswith('.local') else ''):
+        c = str(cand or '').strip()
+        if len(c) >= 3 and c not in out:
+            out.append(c)
+    return out
+
+
+_HOST_RE = None
+
+
+def redact(text: str, cap: int = DETAIL_MAX) -> str:
+    """脱敏 + 截断。宁可少信息，也不把客户业务值/凭据/**主机名**带上去。"""
+    global _HOST_RE
+    out = str(text or '')
+    if _HOST_RE is None:
+        vs = _host_variants()
+        _HOST_RE = re.compile('|'.join(re.escape(v) for v in vs), re.I) if vs else False
+    if _HOST_RE:
+        out = _HOST_RE.sub('HOST***', out)
+    for pat, rep in _SENSITIVE:
+        out = pat.sub(rep, out)
+    out = out.replace('\n', ' ⏎ ')
+    if len(out) > cap:
+        out = out[:cap] + '…'
+    return out
+
+
+def case_hash(case_id: str) -> str:
+    """票号只上报哈希：能关联同一张票的多次事件，又不把业务主键送到云端。"""
+    return hashlib.sha256(str(case_id or '').encode('utf-8')).hexdigest()[:12] if case_id else ''
+
+
+# ── outbox / state ───────────────────────────────────────────────────────────
+def _append_locked(path: pathlib.Path, line: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, 'a', encoding='utf-8') as f:
+        # outbox 追加写：策略 (b) **响亮降级**（本模块的契约是"绝不阻断主流程"，
+        # 见模块 docstring；旧实现在 Windows 上静默无锁）。出声 = stderr 一行 + 进程内计数。
+        with best_effort(f, site='telemetry.append', note='outbox 追加降级为无锁写'):
+            f.write(line)
+            f.flush()
+            os.fsync(f.fileno())
+
+
+def read_state() -> dict:
+    try:
+        return json.loads(state_path().read_text(encoding='utf-8'))
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def write_state(**kv) -> None:
+    st = read_state()
+    st.update(kv)
+    try:
+        state_path().parent.mkdir(parents=True, exist_ok=True)
+        state_path().write_text(json.dumps(st, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def read_outbox() -> list:
+    out = []
+    p = outbox_path()
+    if not p.exists():
+        return out
+    for ln in p.read_text(encoding='utf-8', errors='replace').splitlines():
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            rec = json.loads(ln)
+        except Exception:  # noqa: BLE001
+            continue
+        if isinstance(rec, dict) and rec.get('eventId'):
+            out.append(rec)
+    return out
+
+
+def write_outbox(events: list) -> None:
+    """重写 outbox（丢最旧的超出部分，并计数）。"""
+    dropped = 0
+    evs = events
+    if len(evs) > OUTBOX_MAX_EVENTS:
+        dropped = len(evs) - OUTBOX_MAX_EVENTS
+        evs = evs[-OUTBOX_MAX_EVENTS:]
+    body = ''.join(json.dumps(e, ensure_ascii=False) + '\n' for e in evs)
+    while len(body.encode('utf-8')) > OUTBOX_MAX_BYTES and evs:
+        dropped += 1
+        evs = evs[1:]
+        body = ''.join(json.dumps(e, ensure_ascii=False) + '\n' for e in evs)
+    try:
+        outbox_path().parent.mkdir(parents=True, exist_ok=True)
+        with open(outbox_path(), 'w', encoding='utf-8') as f:
+            # 重写 outbox：同上，策略 (b) 响亮降级（外层已 try/except 兜住"遥测绝不影响调用方"）
+            with best_effort(f, site='telemetry.rewrite', note='outbox 重写降级为无锁写'):
+                f.write(body)
+                f.flush()
+    except Exception:  # noqa: BLE001
+        return
+    if dropped:
+        write_state(droppedEvents=int(read_state().get('droppedEvents') or 0) + dropped)
+
+
+def purge_outbox(reason: str = '') -> int:
+    """**清空**本地队列（只删本地文件，绝不联网）。返回清掉的条数。
+
+    用在两处：① 关闭状态下 `flush`（"关闭期不采集、不堆积、不补发"）；
+    ② `--purge`（设置页关掉开关 / 运维手动撤回同意）。
+    计数写进 `state.json` 便于事后核对（"到底扔了多少"）。
+    """
+    n = 0
+    try:
+        n = len(read_outbox())
+        p = outbox_path()
+        if p.exists():
+            p.unlink()
+        if n or reason:
+            write_state(**{
+                'purgedTotal': int(read_state().get('purgedTotal') or 0) + n,
+                'lastPurgeAt': dt.datetime.now().isoformat(timespec='seconds'),
+                'lastPurgeReason': str(reason or ''),
+            })
+    except Exception:  # noqa: BLE001
+        pass
+    return n
+
+
+def split_consented(events: list) -> tuple:
+    """按**采集时刻的同意标记**分流 ⇒ (可发送, 无标记条数)。
+
+    无标记 = 升级前（"默认开"时代）采集的遗留事件，或任何绕过 `emit()` 塞进来的行。
+    它们**永不外发**（迁移语义见模块头）。
+    """
+    keep = [e for e in events if e.get('consent') == CONSENT_TAG]
+    return keep, len(events) - len(keep)
+
+
+def build_event(kind: str, *, capability='', flow='', role='', case='', phase='',
+                error_class='', attempt=0, duration_sec=0, detail='', is_test=False) -> dict:
+    inst = ensure_instance()
+    return {
+        'eventId': uuid.uuid4().hex,
+        'kind': kind,
+        'instanceId': inst.get('installId', ''),
+        'consent': CONSENT_TAG,          # 采集时刻的同意标记（**只在本地**，_post 会剔除）
+        'ts': dt.datetime.now(dt.timezone.utc).isoformat(timespec='seconds'),
+        'version': repo_version(),
+        'capability': capability or '',
+        'flow': flow or '',
+        'role': role or '',
+        'caseHash': case_hash(case),
+        'phase': phase or '',
+        'errorClass': error_class or '',
+        'attempt': int(attempt or 0),
+        'durationSec': int(duration_sec or 0),
+        # 2026-10-04（合规）：**不再上报原始 hostname**，改上报不可逆短哈希（os/arch 保留）。
+        'hostHash': inst.get('hostHash') or host_hash(str(inst.get('host') or ''), str(inst.get('hostSalt') or '')),
+        'os': inst.get('os', ''),
+        'arch': inst.get('arch', ''),
+        'profile': (os.environ.get('DSH_PROFILE') or 'web')[:32],
+        'packVersions': pack_versions(),
+        'detail': redact(detail),
+        'isTest': bool(is_test),
+    }
+
+
+def emit(kind: str, **kw) -> dict | None:
+    """采集一条事件（**只落本地**，不联网；联网交给 flush）。任何异常都吞掉。"""
+    try:
+        if not telemetry_enabled() or kind not in EVENT_KINDS:
+            return None
+        ev = build_event(kind, **kw)
+        _append_locked(outbox_path(), json.dumps(ev, ensure_ascii=False) + '\n')
+        write_state(lastEmitAt=ev['ts'], lastEmitKind=kind)
+        return ev
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def heartbeat(force: bool = False) -> dict | None:
+    """心跳：每天最多一条（"客户机还活着"的唯一信号）。
+
+    ⚠️ 2026-10-04（合规）：**不再把主机名写进 detail**（旧实现是 `detail=f'host={...}'`）。
+    要分辨机器看 `instanceId` / `hostHash` 两个字段就够了。
+    """
+    today = dt.date.today().isoformat()
+    st = read_state()
+    if not force and st.get('lastHeartbeatDate') == today:
+        return None
+    ev = emit('heartbeat', detail='')
+    if ev:
+        write_state(lastHeartbeatDate=today)
+    return ev
+
+
+def _post(ev: dict) -> tuple[bool, int, str]:
+    cred = credential()
+    if cred['kind'] == 'none':
+        # fail-closed：没有可用凭证就不发（宁可不报，也不匿名上报）。`note` 说明为什么。
+        return False, 0, (cred.get('note') or 'no-token')
+    # `eventId` 按协议回填；`consent` 是**本地闸门**，绝不出网（服务端字段契约一个字不变）。
+    body = {k: v for k, v in ev.items() if k not in ('eventId', 'consent')} | {'eventId': ev.get('eventId', '')}
+    headers = {'Content-Type': 'application/json'}
+    if cred['kind'] == 'instance':
+        # 机器自带凭证：令牌进专用头；⛔ 不带 Authorization（避免服务端把过期的账号 JWT 也看一遍）
+        headers.update(cred['headers'])
+    else:
+        headers['Authorization'] = 'Bearer ' + cred['token']
+    req = urllib.request.Request(
+        api_base() + ENDPOINT,
+        data=json.dumps(body, ensure_ascii=False).encode('utf-8'),
+        headers=headers,
+        method='POST',
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=HTTP_TIMEOUT) as resp:
+            if 200 <= resp.status < 300:
+                return True, resp.status, ''
+            return False, resp.status, f'http {resp.status}'
+    except urllib.error.HTTPError as e:                      # 4xx/5xx 有状态码
+        return False, int(getattr(e, 'code', 0) or 0), f'http {e.code}'
+    except Exception as e:                                    # noqa: BLE001  网络类
+        return False, 0, type(e).__name__
+
+
+def _telemetry_off() -> bool:
+    """测试/离线开关（2026-09-30）：`ARGENT_TELEMETRY_OFF=1` ⇒ **绝不发网**（仅本地队列）。
+    背景：测试夹具流程（如 `flowA`）曾把"流程异常·needs_agent"推到生产告警（维护者被刷）。"""
+    return str(os.environ.get("ARGENT_TELEMETRY_OFF", "")).strip() in ("1", "true", "True", "yes")
+
+
+def flush(max_events: int = 20, force: bool = False) -> dict:
+    if _telemetry_off():
+        return {"ok": True, "skipped": "ARGENT_TELEMETRY_OFF=1（测试/离线）"}
+    """把 outbox 里的队头若干条发出去。退避期内直接跳过（不刷屏、不耗流量）。
+
+    `force=True` 忽略退避（运维手改端点后"立刻重试一次"、以及测试用）。
+    """
+    res = {'attempted': 0, 'sent': 0, 'failed': 0, 'skipped': ''}
+    try:
+        if not telemetry_enabled():
+            # 「关闭期不采集、不堆积、不补发」：关闭状态下顺手把本地队列清空（只删本地文件）。
+            n = purge_outbox('flush-disabled')
+            res['skipped'] = 'disabled'
+            if n:
+                res['purgedWhileDisabled'] = n
+                res['skipped'] = f'disabled（已清空本地队列 {n} 条）'
+            return res
+        st = read_state()
+        until = float(st.get('backoffUntil') or 0)
+        if until > time.time() and not force:
+            res['skipped'] = f'backoff {int(until - time.time())}s'
+            return res
+        queue = read_outbox()
+        # 迁移语义：**无同意标记**的事件（升级前"默认开"时代采集的遗留）永不外发 ⇒ 先剔除落盘。
+        if any(e.get('consent') != CONSENT_TAG for e in queue):
+            queue, untagged = split_consented(queue)
+            write_outbox(queue)
+            write_state(droppedUnconsented=int(read_state().get('droppedUnconsented') or 0) + untagged)
+            res['droppedUnconsented'] = untagged
+        if not queue:
+            res['skipped'] = 'empty'
+            return res
+        sent_ids, remain = [], []
+        bail = False
+        for ev in queue[:max_events]:
+            if bail:                       # 服务端不可用就别继续打
+                remain.append(ev)
+                continue
+            ok, code, why = _post(ev)
+            res['attempted'] += 1
+            if ok:
+                res['sent'] += 1
+                sent_ids.append(ev)
+            else:
+                res['failed'] += 1
+                res['lastError'] = f'{why}'
+                remain.append(ev)
+                if code in GONE_CODES or code == 0:
+                    bail = True            # 长退避：未登录/未订阅/端点未部署/断网
+        remain.extend(queue[max_events:])
+        write_outbox(remain)
+        if sent_ids:
+            _append_locked(sent_path(), ''.join(
+                json.dumps({'eventId': e['eventId'], 'kind': e['kind'], 'at': dt.datetime.now().isoformat(timespec='seconds')},
+                           ensure_ascii=False) + '\n' for e in sent_ids))
+            _trim_sent()
+            write_state(lastSuccessAt=dt.datetime.now().isoformat(timespec='seconds'),
+                        sentTotal=int(read_state().get('sentTotal') or 0) + len(sent_ids))
+        if res['failed']:
+            fails = int(read_state().get('consecutiveFailures') or 0) + 1
+            backoff = min(BACKOFF_BASE_SEC * (2 ** (fails - 1)), BACKOFF_MAX_SEC)
+            write_state(consecutiveFailures=fails, backoffUntil=time.time() + backoff,
+                        lastError=res.get('lastError', ''), lastErrorAt=dt.datetime.now().isoformat(timespec='seconds'))
+            res['backoffSec'] = int(backoff)
+        else:
+            write_state(consecutiveFailures=0, backoffUntil=0, lastError='')
+        return res
+    except Exception as e:  # noqa: BLE001
+        res['skipped'] = f'error {type(e).__name__}'
+        return res
+
+
+def _trim_sent() -> None:
+    try:
+        lines = sent_path().read_text(encoding='utf-8', errors='replace').splitlines()
+        if len(lines) > SENT_RING:
+            sent_path().write_text('\n'.join(lines[-SENT_RING:]) + '\n', encoding='utf-8')
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def status() -> dict:
+    st = read_state()
+    q = read_outbox()
+    sendable, untagged = split_consented(q)
+    inst = ensure_instance()
+    until = float(st.get('backoffUntil') or 0)
+    cred = credential()
+    tok = instance_token()
+    exp = str(tok.get('exp') or '')
+    expired = False
+    if exp:
+        try:
+            expired = dt.datetime.fromisoformat(exp.replace('Z', '+00:00')) < dt.datetime.now(dt.timezone.utc)
+        except Exception:  # noqa: BLE001
+            expired = False
+    me = str(inst.get('installId') or '')
+    return {
+        'enabled': telemetry_enabled(),
+        'optIn': _config_opt_in(),          # 配置里的显式同意（不含硬关的影响）
+        'hardOff': os.environ.get('TELEMETRY_DISABLE') in ('1', 'true', 'yes'),
+        'endpoint': api_base() + ENDPOINT,
+        'hasToken': bool(cred['token']),
+        # ── 凭证来源（2026-10-05「机器自带凭证」）──────────────────────────────
+        # ⛔ **只显示类型/来源，绝不显示值**（令牌串绝不进日志/状态输出）。
+        'credential': {
+            'kind': cred['kind'],                       # instance ｜ account ｜ none
+            'source': ('instance-token' if cred['kind'] == 'instance' and cred['source'].startswith('file:')
+                       else 'instance-token-env' if cred['kind'] == 'instance'
+                       else 'account-jwt' if cred['kind'] == 'account' else 'none'),
+            'header': (INSTANCE_TOKEN_HEADER if cred['kind'] == 'instance'
+                       else 'authorization' if cred['kind'] == 'account' else ''),
+            'note': cred.get('note', ''),
+            # 下面是**元数据**（不是令牌本身）：到期日 / 绑定 / 是否与令牌声明的实例一致
+            'exp': exp, 'expired': expired,
+            'tokenInstanceId': tok.get('instanceId', ''),
+            'tokenDeviceBound': bool(tok.get('deviceCode')),
+            'localInstanceId': me,
+            'instanceMatch': (not tok.get('instanceId')) or tok.get('instanceId') == me,
+            'tokenFile': str(instance_token_path()),
+        },
+        'instanceId': me,
+        # `host` 是**本机自检**用（只在这个终端里看得到，绝不随事件外发）；外发字段是 hostHash。
+        'host': inst.get('host', ''),
+        'hostHash': inst.get('hostHash', ''),
+        'version': repo_version(),
+        'queued': len(sendable),
+        'queuedKinds': {k: sum(1 for e in sendable if e.get('kind') == k) for k in EVENT_KINDS},
+        'queuedUnconsented': untagged,      # 无同意标记（升级前遗留）⇒ 永不外发，下次 flush 剔除
+        'sentTotal': int(st.get('sentTotal') or 0),
+        'droppedEvents': int(st.get('droppedEvents') or 0),
+        'droppedUnconsented': int(st.get('droppedUnconsented') or 0),
+        'purgedTotal': int(st.get('purgedTotal') or 0),
+        'consecutiveFailures': int(st.get('consecutiveFailures') or 0),
+        'backoffSecLeft': max(0, int(until - time.time())),
+        'lastSuccessAt': st.get('lastSuccessAt', ''),
+        'lastError': st.get('lastError', ''),
+        'lastHeartbeatDate': st.get('lastHeartbeatDate', ''),
+    }
+
+
+def preview(limit: int = 5) -> list:
+    """打印"**将要发什么**" —— 只列真会被发出去的（带同意标记的）那些。"""
+    return split_consented(read_outbox())[0][:limit]
+
+
+# ── CLI ──────────────────────────────────────────────────────────────────────
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='遥测上报（元数据事件；绝不阻断主流程）')
+    ap.add_argument('--emit', action='store_true', help='采集一条事件（只落本地队列）')
+    ap.add_argument('--heartbeat', action='store_true', help='每天一条心跳（去重）')
+    ap.add_argument('--force', action='store_true', help='心跳忽略"今天已发"')
+    ap.add_argument('--flush', action='store_true', help='把队列发出去（有退避）')
+    ap.add_argument('--max', type=int, default=20, help='--flush 单次最多发几条')
+    ap.add_argument('--preview', action='store_true', help='打印将要上报的内容（脱敏后）')
+    ap.add_argument('--status', action='store_true', help='打印队列/退避/实例身份')
+    ap.add_argument('--purge', action='store_true', help='清空本地队列（关闭上报/撤回同意时用；只删本地文件）')
+    ap.add_argument('--init-instance', action='store_true', help='创建 instance.json')
+    ap.add_argument('--kind', choices=EVENT_KINDS, default='failure')
+    ap.add_argument('--capability', default='')
+    ap.add_argument('--flow', default='')
+    ap.add_argument('--role', default='')
+    ap.add_argument('--case', default='', help='票号（只上报其哈希）')
+    ap.add_argument('--phase', default='')
+    ap.add_argument('--error-class', dest='error_class', default='')
+    ap.add_argument('--attempt', type=int, default=0)
+    ap.add_argument('--duration-sec', dest='duration_sec', type=int, default=0)
+    ap.add_argument('--detail', default='')
+    ap.add_argument('--test', action='store_true', help='演练事件（服务端不推维护者）')
+    a = ap.parse_args(argv)
+
+    try:
+        if a.init_instance:
+            inst = ensure_instance()
+            print(json.dumps(inst, ensure_ascii=False, indent=2))
+            return 0
+        if a.status:
+            print(json.dumps(status(), ensure_ascii=False, indent=2))
+            return 0
+        if a.purge:
+            n = purge_outbox('cli')
+            print(f'purge: 已清空本地队列 {n} 条（未联网）')
+            return 0
+        if a.preview:
+            for ev in preview(a.max):
+                print(json.dumps(ev, ensure_ascii=False, indent=2))
+            return 0
+        if a.heartbeat:
+            ev = heartbeat(force=a.force)
+            print('heartbeat: ' + ('queued' if ev else 'skipped（今天已发）'))
+        if a.emit:
+            ev = emit(a.kind, capability=a.capability, flow=a.flow, role=a.role, case=a.case,
+                      phase=a.phase, error_class=a.error_class, attempt=a.attempt,
+                      duration_sec=a.duration_sec, detail=a.detail, is_test=a.test)
+            print('emit: ' + ('queued' if ev else 'skipped（关闭或参数不合法）'))
+        if a.flush or a.heartbeat or a.emit:
+            r = flush(a.max, force=a.force)
+            print('flush: ' + json.dumps(r, ensure_ascii=False))
+        if not any([a.emit, a.heartbeat, a.flush, a.preview, a.status, a.init_instance, a.purge]):
+            ap.print_help()
+        return 0
+    except Exception as e:  # noqa: BLE001  —— 遥测永远不许把调用方搞崩
+        print(f'telemetry 忽略异常: {type(e).__name__}: {e}', file=sys.stderr)
+        return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())