coze_lab 0.1.22 → 0.1.23

package/README.md

@@ -24,7 +24,7 @@ npx coze_lab --logout     # Clear cached credentials
 |-----------|----------|-----------------|
 | `--agent` | ✓ (for setup) | `claude-code`, `codex`, `openclaw` |
 | `--agent-id` | — | Resolve `~/.coze/agents/<agentId>/config.json` and write per-agent config |
-| `--cloud` | — | Cloud mode: read token from env and emit `COZE_LAB_RESULT=...` |
+| `--cloud` | — | Cloud mode: read trace token from env and emit `COZE_LAB_RESULT=...` |
 | `--codex-home` | — | Override Codex config home for non-cloud/custom runs |
 | `--login` | — | Run the Device Code login flow only |
 | `--status` | — | Print local token status (valid / expiring / expired) |
@@ -70,6 +70,12 @@ created after a new Codex turn, Codex did not load or execute the hook.
 
 OAuth tokens are stored in `~/.cozeloop/credentials.json` (mode 600).
 
+In cloud mode, trace verification and hook uploads require
+`COZELOOP_API_TOKEN`. `COZE_API_TOKEN` is kept only as a legacy compatibility
+signal for hook injection; it is not treated as a CozeLoop SDK trace ingest
+token. If cloud only provides `COZE_API_TOKEN`, onboard still writes the hook
+configuration but reports `verify=fail` with `token_source=COZE_API_TOKEN`.
+
 **At hook execution time** (Claude Code / Codex), the Python hook script automatically:
 1. Reads `~/.cozeloop/credentials.json`
 2. If the token expires in < 10 minutes, calls the Coze refresh API

package/index.js

@@ -17,7 +17,7 @@ const REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
 // 云端（--cloud）模式：在 stdout 输出一行机器可读结果 COZE_LAB_RESULT={...}，
 // 供管理后台解析判定（inject/verify/logid/message），不依赖中文文案。
 let CLOUD_MODE = false;
-const cloudResult = { version: PACKAGE_VERSION, inject: 'skip', verify: 'skip', logid: '', message: '' };
+const cloudResult = { version: PACKAGE_VERSION, inject: 'skip', verify: 'skip', logid: '', message: '', token_source: '' };
 
 // errorBox 在云端模式下抛此异常（而非 process.exit），由 main 外层统一收尾。
 class CloudAbort extends Error {}
@@ -40,6 +40,22 @@ function emitCloudResult() {
   console.log('COZE_LAB_RESULT=' + JSON.stringify(safe));
 }
 
+function readEnv(name) {
+  return String(process.env[name] || '').trim();
+}
+
+function getCloudTokenInfo() {
+  const loopToken = readEnv('COZELOOP_API_TOKEN');
+  if (loopToken) {
+    return { token: loopToken, source: 'COZELOOP_API_TOKEN', traceUsable: true };
+  }
+  const cozeToken = readEnv('COZE_API_TOKEN');
+  if (cozeToken) {
+    return { token: cozeToken, source: 'COZE_API_TOKEN', traceUsable: false };
+  }
+  return { token: '', source: '', traceUsable: false };
+}
+
 // ─── 1. Color helpers ────────────────────────────────────────────────────────
 const C = {
   reset:  '\x1b[0m',
@@ -4526,22 +4542,26 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cl
     if (!existing.env) existing.env = {};
     existing.env.COZELOOP_WORKSPACE_ID = workspaceId;
     if (cloud) {
-      if (process.env.COZELOOP_API_TOKEN) {
-        existing.env.COZELOOP_API_TOKEN = process.env.COZELOOP_API_TOKEN;
+      const loopToken = readEnv('COZELOOP_API_TOKEN');
+      const cozeToken = readEnv('COZE_API_TOKEN');
+      if (loopToken) {
+        existing.env.COZELOOP_API_TOKEN = loopToken;
         delete existing.env.COZE_API_TOKEN;
-      } else if (process.env.COZE_API_TOKEN) {
-        existing.env.COZE_API_TOKEN = process.env.COZE_API_TOKEN;
+      } else if (cozeToken) {
+        existing.env.COZE_API_TOKEN = cozeToken;
         delete existing.env.COZELOOP_API_TOKEN;
       }
     } else {
       existing.env.COZELOOP_API_TOKEN = patToken;
       delete existing.env.COZE_API_TOKEN;
     }
-    if (process.env.COZELOOP_API_BASE_URL) {
-      existing.env.COZELOOP_API_BASE_URL = process.env.COZELOOP_API_BASE_URL;
+    const loopBaseUrl = readEnv('COZELOOP_API_BASE_URL');
+    const otelEndpoint = readEnv('OTEL_ENDPOINT');
+    if (loopBaseUrl) {
+      existing.env.COZELOOP_API_BASE_URL = loopBaseUrl;
       delete existing.env.OTEL_ENDPOINT;
-    } else if (process.env.OTEL_ENDPOINT) {
-      existing.env.OTEL_ENDPOINT = process.env.OTEL_ENDPOINT;
+    } else if (otelEndpoint) {
+      existing.env.OTEL_ENDPOINT = otelEndpoint;
       delete existing.env.COZELOOP_API_BASE_URL;
     }
     // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
@@ -4584,10 +4604,12 @@ function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
     shellEnvLine('COZELOOP_WORKSPACE_ID', workspaceId),
   ];
   if (cloud) {
-    if (process.env.COZELOOP_API_TOKEN) {
-      envLines.push(shellEnvLine('COZELOOP_API_TOKEN', process.env.COZELOOP_API_TOKEN));
-    } else if (process.env.COZE_API_TOKEN) {
-      envLines.push(shellEnvLine('COZE_API_TOKEN', process.env.COZE_API_TOKEN));
+    const loopToken = readEnv('COZELOOP_API_TOKEN');
+    const cozeToken = readEnv('COZE_API_TOKEN');
+    if (loopToken) {
+      envLines.push(shellEnvLine('COZELOOP_API_TOKEN', loopToken));
+    } else if (cozeToken) {
+      envLines.push(shellEnvLine('COZE_API_TOKEN', cozeToken));
     }
   } else {
     envLines.push(shellEnvLine('COZELOOP_API_TOKEN', token));
@@ -4595,10 +4617,12 @@ function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
   envLines.push(shellEnvLine('CODEX_HOME', home));
   envLines.push(shellEnvLine('COZELOOP_HOOK_LOG', logFile));
   envLines.push('TRACE_TO_COZELOOP=true');
-  if (process.env.COZELOOP_API_BASE_URL) {
-    envLines.push(shellEnvLine('COZELOOP_API_BASE_URL', process.env.COZELOOP_API_BASE_URL));
-  } else if (process.env.OTEL_ENDPOINT) {
-    envLines.push(shellEnvLine('OTEL_ENDPOINT', process.env.OTEL_ENDPOINT));
+  const loopBaseUrl = readEnv('COZELOOP_API_BASE_URL');
+  const otelEndpoint = readEnv('OTEL_ENDPOINT');
+  if (loopBaseUrl) {
+    envLines.push(shellEnvLine('COZELOOP_API_BASE_URL', loopBaseUrl));
+  } else if (otelEndpoint) {
+    envLines.push(shellEnvLine('OTEL_ENDPOINT', otelEndpoint));
   }
   // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
   envLines.push(shellEnvLine('x_tt_env', PPE_TT_ENV));
@@ -4909,8 +4933,9 @@ function runCommand(input) {
   });
 }
 
-async function verifyTraceReportViaSdk(token, workspaceId, pairCode, pythonCmd) {
+async function verifyTraceReportViaSdk(token, workspaceId, pairCode, pythonCmd, tokenSource) {
   const pair = pairCode || crypto.randomBytes(6).toString('hex');
+  const apiBase = getCozeloopApiBaseUrl(true);
   const script = `
 import json
 import os
@@ -4941,11 +4966,11 @@ try:
     client.flush()
     client.close()
     if events:
-        print(json.dumps({"success": False, "body": "\\n".join(events)}, ensure_ascii=False))
+        print(json.dumps({"success": False, "body": "\\n".join(events), "api_base_url": os.environ.get("COZELOOP_API_BASE_URL", ""), "token_source": os.environ.get("COZELOOP_TOKEN_SOURCE", "")}, ensure_ascii=False))
         sys.exit(1)
-    print(json.dumps({"success": True, "body": ""}, ensure_ascii=False))
+    print(json.dumps({"success": True, "body": "", "api_base_url": os.environ.get("COZELOOP_API_BASE_URL", ""), "token_source": os.environ.get("COZELOOP_TOKEN_SOURCE", "")}, ensure_ascii=False))
 except Exception as e:
-    print(json.dumps({"success": False, "body": str(e)}, ensure_ascii=False))
+    print(json.dumps({"success": False, "body": str(e), "api_base_url": os.environ.get("COZELOOP_API_BASE_URL", ""), "token_source": os.environ.get("COZELOOP_TOKEN_SOURCE", "")}, ensure_ascii=False))
     sys.exit(1)
 `;
   const env = {
@@ -4953,10 +4978,10 @@ except Exception as e:
     COZELOOP_WORKSPACE_ID: workspaceId,
     COZELOOP_API_TOKEN: token,
     COZELOOP_PAIR_CODE: pair,
+    COZELOOP_TOKEN_SOURCE: tokenSource || '',
     x_tt_env: PPE_TT_ENV,
     x_use_ppe: PPE_USE_PPE,
   };
-  const apiBase = getCozeloopApiBaseUrl(true);
   if (apiBase) env.COZELOOP_API_BASE_URL = apiBase;
   const result = await runCommand({
     cmd: pythonCmd || 'python3',
@@ -4976,10 +5001,11 @@ except Exception as e:
     info(`查询方可用 pair_code=${pair} 在 CozeLoop 回查确认该 trace 已落库。`);
   } else {
     warn(`trace 上报失败: SDK selfcheck exit ${result.code}`);
+    info(`trace selfcheck api_base_url=${apiBase || COZE_API}, token_source=${tokenSource || 'unknown'}`);
     const snippet = String(body || '').slice(0, 300);
     if (snippet) console.log(snippet);
   }
-  return { success, status: result.code || 0, body, traceId: '', pairCode: pair };
+  return { success, status: result.code || 0, body, traceId: '', pairCode: pair, apiBaseUrl: apiBase, tokenSource };
 }
 
 // 真实发一条最小 OTLP trace 到 CozeLoop，验证上报链路是否打通。
@@ -5394,25 +5420,37 @@ async function main() {
 
   // Step 1: Authorize.
   //   云端（--cloud）：token 取自 sandbox 注入的环境变量，跳过 OAuth / credentials.json。
-  //     云端真实变量名是 COZELOOP_API_TOKEN（兼容历史的 COZE_API_TOKEN）。
+  //     trace 上报需要 COZELOOP_API_TOKEN；COZE_API_TOKEN 只保留为历史兼容来源，
+  //     onboard 会写入 hook，但自检会明确标记它不是 CozeLoop ingest token。
   //   本地：load cached → refresh → device code。
   //   注意：workspace_id 始终用写死的 WORKSPACE_ID（团队固定上报 workspace），不读环境。
   let token;
+  let tokenSource = '';
+  let cloudTraceUsableToken = true;
   if (args.cloud) {
-    info('Step 1/5: 云端模式，从环境变量读取 COZELOOP_API_TOKEN...');
-    token = process.env.COZELOOP_API_TOKEN || process.env.COZE_API_TOKEN;
+    info('Step 1/5: 云端模式，从环境变量读取 trace token...');
+    const tokenInfo = getCloudTokenInfo();
+    token = tokenInfo.token;
+    tokenSource = tokenInfo.source;
+    cloudTraceUsableToken = tokenInfo.traceUsable;
     if (!token) {
       errorBox([
         'ERROR: --cloud 模式要求环境变量 COZELOOP_API_TOKEN',
         '',
-        '云端 sandbox 应在进程环境中注入 COZELOOP_API_TOKEN（或 COZE_API_TOKEN）。',
+        '云端 sandbox 应在进程环境中注入 COZELOOP_API_TOKEN。',
         '未检测到该变量，无法配置 trace 上报。',
       ]);
     }
-    ok('已从环境变量读取 COZELOOP_API_TOKEN');
+    cloudResult.token_source = tokenSource;
+    if (cloudTraceUsableToken) {
+      ok(`已从环境变量读取 ${tokenSource}`);
+    } else {
+      warn('仅检测到 COZE_API_TOKEN；它不是 CozeLoop SDK trace ingest token，自检预计会失败。');
+    }
   } else {
     info('Step 1/5: 检查授权状态...');
     token = await getValidToken();
+    tokenSource = 'credentials';
   }
   console.log('');
 
@@ -5496,9 +5534,24 @@ async function main() {
 
   // Step 5: Verify trace reporting end-to-end
   info('Step 5/5: 验证 trace 上报链路...');
-  const verifyResult = args.cloud
-    ? await verifyTraceReportViaSdk(token, WORKSPACE_ID, args.pairCode, pythonCmd || 'python3')
-    : await verifyTraceReport(token, WORKSPACE_ID, args.pairCode, getOtelTracesUrl(false));
+  let verifyResult;
+  if (args.cloud && !cloudTraceUsableToken) {
+    verifyResult = {
+      success: false,
+      status: 0,
+      body: '云端仅提供 COZE_API_TOKEN。Coze API token 不能作为 CozeLoop Python SDK 的 COZELOOP_API_TOKEN 上报 trace；请注入具备 CozeLoop trace ingest 权限的 COZELOOP_API_TOKEN。',
+      traceId: '',
+      pairCode: args.pairCode || '',
+      tokenSource,
+      apiBaseUrl: getCozeloopApiBaseUrl(true),
+    };
+    warn('trace 上报跳过：缺少 COZELOOP_API_TOKEN。');
+    console.log(verifyResult.body);
+  } else {
+    verifyResult = args.cloud
+      ? await verifyTraceReportViaSdk(token, WORKSPACE_ID, args.pairCode, pythonCmd || 'python3', tokenSource)
+      : await verifyTraceReport(token, WORKSPACE_ID, args.pairCode, getOtelTracesUrl(false));
+  }
   if (verifyResult.success) {
     cloudResult.verify = 'ok';
   } else if (CLOUD_MODE) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coze_lab",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to CozeLoop",
   "keywords": [
     "cozeloop",

package/scripts/claude-code/cozeloop_hook.py

@@ -269,11 +269,10 @@ def get_api_base_url() -> str:
 
 def get_fresh_token() -> Optional[str]:
     """Return a valid access token, refreshing if needed. Falls back to env var."""
-    api_base_url = get_api_base_url()
     env_token = os.environ.get("COZELOOP_API_TOKEN")
     env_coze_token = os.environ.get("COZE_API_TOKEN")
-    if api_base_url and (env_token or env_coze_token):
-        return env_token or env_coze_token
+    if env_token:
+        return env_token
     creds = _load_credentials()
     if creds:
         expires_at_sec = creds.get("expires_at", 0) / 1000
@@ -287,12 +286,8 @@ def get_fresh_token() -> Optional[str]:
             if new_token:
                 return new_token
             debug_log("Refresh failed, falling back to env var.")
-    if env_token:
-        return env_token
-    if api_base_url:
-        return env_coze_token
     if env_coze_token:
-        debug_log("COZE_API_TOKEN present but ignored without COZELOOP_API_BASE_URL or OTEL_ENDPOINT")
+        debug_log("COZE_API_TOKEN present but ignored; CozeLoop trace upload requires COZELOOP_API_TOKEN")
     return None
 
 # -------------------------------------------------------------------------

package/scripts/codex/cozeloop_hook.py

@@ -230,11 +230,10 @@ def get_api_base_url() -> str:
 
 
 def get_fresh_token():
-    api_base_url = get_api_base_url()
     env_token = os.environ.get("COZELOOP_API_TOKEN")
     env_coze_token = os.environ.get("COZE_API_TOKEN")
-    if api_base_url and (env_token or env_coze_token):
-        return env_token or env_coze_token
+    if env_token:
+        return env_token
     creds = _load_credentials()
     if creds:
         remaining = creds.get("expires_at", 0) / 1000 - time.time()
@@ -244,12 +243,8 @@ def get_fresh_token():
             new_token = _refresh_token(creds["refresh_token"])
             if new_token:
                 return new_token
-    if env_token:
-        return env_token
-    if api_base_url:
-        return env_coze_token
     if env_coze_token:
-        hook_log("COZE_API_TOKEN present but ignored without COZELOOP_API_BASE_URL or OTEL_ENDPOINT")
+        hook_log("COZE_API_TOKEN present but ignored; CozeLoop trace upload requires COZELOOP_API_TOKEN")
     return None
 # -------------------------------------------------------------------------