coze_lab 0.1.21 → 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',
@@ -4472,8 +4488,6 @@ function shellEnvLine(key, value) {
 // writeClaudeCodeHook 配置 Claude Code 的 hook。
 // configBaseDir 缺省 process.cwd()（全局/项目级）；传入 agent 的 workspace 则 per-agent：
 // settings.json + 凭证写进 <configBaseDir>/.claude，仅该 agent（以此为 cwd 启动）生效。
-// cloud=true 时不把明文 token 写进 settings.local.json —— 云端 hook 运行时直接读
-// 环境变量 COZE_API_TOKEN（见 scripts/claude-code/cozeloop_hook.py 的 get_fresh_token）。
 function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cloud) {
   const hooksDir    = path.join(os.homedir(), '.claude', 'hooks');
   const hookScript  = path.join(hooksDir, 'cozeloop_hook.py');
@@ -4527,12 +4541,28 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cl
   const localSettings = mergeJson(localSettingsPath, (existing) => {
     if (!existing.env) existing.env = {};
     existing.env.COZELOOP_WORKSPACE_ID = workspaceId;
-    // 云端：token 由 sandbox 注入到环境变量 COZE_API_TOKEN，hook 运行时直接读，
-    // 不在配置文件落明文 token。本地：写入 OAuth 拿到的 token。
     if (cloud) {
-      delete existing.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 (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;
+    }
+    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 (otelEndpoint) {
+      existing.env.OTEL_ENDPOINT = otelEndpoint;
+      delete existing.env.COZELOOP_API_BASE_URL;
     }
     // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
     existing.env.x_tt_env  = PPE_TT_ENV;
@@ -4574,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));
@@ -4585,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));
@@ -4875,6 +4909,105 @@ function httpsPost(url, body, extraHeaders) {
   });
 }
 
+function runCommand(input) {
+  return new Promise((resolve) => {
+    const { spawn } = require('child_process');
+    const child = spawn(input.cmd, input.args || [], {
+      env: input.env || process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, input.timeoutMs || 30000);
+    child.stdout.on('data', chunk => { stdout += chunk.toString(); });
+    child.stderr.on('data', chunk => { stderr += chunk.toString(); });
+    child.on('close', code => {
+      clearTimeout(timer);
+      resolve({ code: timedOut ? -1 : code, stdout, stderr, timedOut });
+    });
+    child.stdin.end(input.stdin || '');
+  });
+}
+
+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
+import sys
+
+events = []
+
+def finish_event(info):
+    if getattr(info, "is_event_fail", False):
+        events.append(getattr(info, "detail_msg", "") or "trace export failed")
+
+try:
+    import cozeloop
+    kwargs = {
+        "workspace_id": os.environ["COZELOOP_WORKSPACE_ID"],
+        "api_token": os.environ["COZELOOP_API_TOKEN"],
+        "upload_timeout": 30,
+        "trace_finish_event_processor": finish_event,
+    }
+    api_base_url = os.environ.get("COZELOOP_API_BASE_URL", "").strip()
+    if api_base_url:
+        kwargs["api_base_url"] = api_base_url
+    client = cozeloop.new_client(**kwargs)
+    with client.start_span(name="cozelab-onboard-selfcheck", span_type="main", start_new_trace=True) as span:
+        span.set_tags({"pair_code": os.environ.get("COZELOOP_PAIR_CODE", ""), "source": "cozelab-onboard"})
+        span.set_input("cozelab-onboard selfcheck")
+        span.set_output("ok")
+    client.flush()
+    client.close()
+    if events:
+        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": "", "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), "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 = {
+    ...process.env,
+    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,
+  };
+  if (apiBase) env.COZELOOP_API_BASE_URL = apiBase;
+  const result = await runCommand({
+    cmd: pythonCmd || 'python3',
+    args: ['-c', script],
+    env,
+    timeoutMs: 45000,
+  });
+  let parsed = null;
+  const out = (result.stdout || '').trim().split(/\n/).filter(Boolean).pop();
+  if (out) {
+    try { parsed = JSON.parse(out); } catch { /* keep null */ }
+  }
+  const body = parsed?.body || result.stderr || result.stdout || (result.timedOut ? 'SDK selfcheck timed out' : '');
+  const success = result.code === 0 && parsed?.success === true;
+  if (success) {
+    ok(`trace 上报成功 (pair_code=${pair})`);
+    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, apiBaseUrl: apiBase, tokenSource };
+}
+
 // 真实发一条最小 OTLP trace 到 CozeLoop，验证上报链路是否打通。
 // 只看 HTTP 状态码（2xx=通），不回查 trace 是否落库——回查由外部查询方完成。
 // pairCode 写进 span 的 pair_code attribute，供查询方按该字段过滤回查；缺省自动生成。
@@ -5287,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('');
 
@@ -5389,7 +5534,24 @@ async function main() {
 
   // Step 5: Verify trace reporting end-to-end
   info('Step 5/5: 验证 trace 上报链路...');
-  const verifyResult = await verifyTraceReport(token, WORKSPACE_ID, args.pairCode, getOtelTracesUrl(args.cloud));
+  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.21",
+  "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

@@ -82,6 +82,7 @@ else:
 DEBUG = os.environ.get("CC_COZELOOP_DEBUG", "").lower() == "true"
 _COZELOOP_CLIENT_ID = "46371084383473718052118955183420.app.coze"
 _COZE_API = "https://api.coze.cn"
+_OTEL_SUFFIX = "/v1/loop/opentelemetry"
 _REFRESH_THRESHOLD = 10 * 60  # refresh when < 10 minutes remain
 _DEFAULT_WORKSPACE_ID = "7644910356078837760"  # hardcoded spaceID fallback
 
@@ -247,8 +248,31 @@ def _refresh_token(refresh_token: str) -> Optional[str]:
         debug_log(f"Token refresh failed: {e}")
     return None
 
+def _normalize_api_base_url(url: str) -> str:
+    base = (url or "").strip().rstrip("/")
+    if base.endswith(_OTEL_SUFFIX + "/v1/traces"):
+        return base[:-len(_OTEL_SUFFIX + "/v1/traces")].rstrip("/")
+    if base.endswith("/api/v1/loop/opentelemetry/v1/traces"):
+        return base[:-len("/v1/loop/opentelemetry/v1/traces")].rstrip("/")
+    if base.endswith(_OTEL_SUFFIX):
+        return base[:-len(_OTEL_SUFFIX)].rstrip("/")
+    if base.endswith("/api/v1/loop/opentelemetry"):
+        return base[:-len("/v1/loop/opentelemetry")].rstrip("/")
+    if base.endswith("/api/v1"):
+        return base[:-len("/v1")].rstrip("/")
+    return base
+
+def get_api_base_url() -> str:
+    return _normalize_api_base_url(
+        os.environ.get("COZELOOP_API_BASE_URL", "") or os.environ.get("OTEL_ENDPOINT", "")
+    )
+
 def get_fresh_token() -> Optional[str]:
     """Return a valid access token, refreshing if needed. Falls back to env var."""
+    env_token = os.environ.get("COZELOOP_API_TOKEN")
+    env_coze_token = os.environ.get("COZE_API_TOKEN")
+    if env_token:
+        return env_token
     creds = _load_credentials()
     if creds:
         expires_at_sec = creds.get("expires_at", 0) / 1000
@@ -262,8 +286,9 @@ def get_fresh_token() -> Optional[str]:
             if new_token:
                 return new_token
             debug_log("Refresh failed, falling back to env var.")
-    # Cloud sandbox: token lives in COZE_API_TOKEN (no credentials.json / refresh).
-    return os.environ.get("COZELOOP_API_TOKEN") or os.environ.get("COZE_API_TOKEN")
+    if env_coze_token:
+        debug_log("COZE_API_TOKEN present but ignored; CozeLoop trace upload requires COZELOOP_API_TOKEN")
+    return None
 
 # -------------------------------------------------------------------------
 
@@ -873,6 +898,9 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
         client_kwargs["workspace_id"] = workspace_id
     if token:
         client_kwargs["api_token"] = token
+    api_base_url = get_api_base_url()
+    if api_base_url:
+        client_kwargs["api_base_url"] = api_base_url
     client = cozeloop.new_client(**client_kwargs)
 
     try:
@@ -1448,5 +1476,3 @@ def main():
 
 if __name__ == "__main__":
     main()
-
-

package/scripts/codex/cozeloop_hook.py

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