coze_lab 0.1.5 → 0.1.7

package/README.md

@@ -1,4 +1,4 @@
-# @cozeloop/onboard
+# coze_lab
 
 Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to CozeLoop.
 
@@ -6,13 +6,13 @@ Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to Coz
 
 ```bash
 # First-time setup — triggers browser OAuth authorization
-npx @cozeloop/onboard --agent=<type>
+npx coze_lab --agent=<type>
 
 # Auth-only commands (no agent configuration)
-npx @cozeloop/onboard --login      # Device Code login only
-npx @cozeloop/onboard --status     # Show current authorization status
-npx @cozeloop/onboard --refresh    # Force-refresh the access token
-npx @cozeloop/onboard --logout     # Clear cached credentials
+npx coze_lab --login      # Device Code login only
+npx coze_lab --status     # Show current authorization status
+npx coze_lab --refresh    # Force-refresh the access token
+npx coze_lab --logout     # Clear cached credentials
 ```
 
 ### Parameters
@@ -62,7 +62,7 @@ OAuth tokens are stored in `~/.cozeloop/credentials.json` (mode 600).
 
 This means traces continue to upload without interruption even across token expiry, as long as the refresh token is still valid.
 
-**For OpenClaw**, the token is read from `openclaw.json` at startup. Re-run `npx @cozeloop/onboard --agent=openclaw` to refresh it if OpenClaw reports auth errors.
+**For OpenClaw**, the token is read from `openclaw.json` at startup. Re-run `npx coze_lab --agent=openclaw` to refresh it if OpenClaw reports auth errors.
 
 ## Supported versions
 

package/index.js

@@ -12,6 +12,33 @@ const CREDS_PATH  = require('path').join(require('os').homedir(), '.cozeloop', '
 // Refresh when less than 10 minutes remain
 const REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
 
+// ─── 1. Cloud structured output ──────────────────────────────────────────────
+// 云端（--cloud）模式：在 stdout 输出一行机器可读结果 COZE_LAB_RESULT={...}，
+// 供管理后台解析判定（inject/verify/logid/message），不依赖中文文案。
+let CLOUD_MODE = false;
+const cloudResult = { inject: 'skip', verify: 'skip', logid: '', message: '' };
+
+// errorBox 在云端模式下抛此异常（而非 process.exit），由 main 外层统一收尾。
+class CloudAbort extends Error {}
+
+// 从 onboard 失败输出 / verify response body 中提取 server logid。
+// 兼容两种形态：JSON 里的 "logid":"xxx" / detail.logid，以及裸 logid=xxx。
+function extractLogid(text) {
+  if (!text) return '';
+  let m = text.match(/"logid"\s*:\s*"([a-zA-Z0-9]+)"/);
+  if (m) return m[1];
+  m = text.match(/logid[=:\s]+([a-zA-Z0-9]+)/i);
+  return m ? m[1] : '';
+}
+
+// 输出结构化结果行（仅云端模式）。
+function emitCloudResult() {
+  if (!CLOUD_MODE) return;
+  // message 压成单行，避免破坏 COZE_LAB_RESULT 单行约定。
+  const safe = { ...cloudResult, message: String(cloudResult.message || '').replace(/\s+/g, ' ').slice(0, 500) };
+  console.log('COZE_LAB_RESULT=' + JSON.stringify(safe));
+}
+
 // ─── 1. Color helpers ────────────────────────────────────────────────────────
 const C = {
   reset:  '\x1b[0m',
@@ -41,6 +68,10 @@ function box(lines, color) {
 
 function errorBox(lines) {
   box(lines, C.red);
+  // 云端模式下不直接退出，改抛异常，让 main 外层统一输出 COZE_LAB_RESULT 结构化结果。
+  if (CLOUD_MODE) {
+    throw new CloudAbort(lines.join(' '));
+  }
   process.exit(1);
 }
 
@@ -4114,6 +4145,8 @@ function parseArgs() {
     if (arg === '--login')   { args['login']   = true; continue; }
     if (arg === '--status')  { args['status']  = true; continue; }
     if (arg === '--refresh') { args['refresh'] = true; continue; }
+    if (arg === '--verify')  { args['verify']  = true; continue; }
+    if (arg === '--cloud')   { args['cloud']   = true; continue; }
     const m = arg.match(/^--([^=]+)=(.+)$/);
     if (m) args[m[1]] = m[2];
   }
@@ -4157,8 +4190,31 @@ function validateArgs(args) {
   if (args['login'])   return { login:   true };
   if (args['status'])  return { status:  true };
   if (args['refresh']) return { refresh: true };
+  if (args['verify'])  return { verify:  true, pairCode: args['pair-code'] };
+
+  // --cloud + --agent-id：云端 sandbox 没有本地 coze-bridge 的 ~/.coze/agents/<id>/config.json，
+  // framework 必须由命令行 --agent 显式传（前端拼命令时已知 agent.framework）。不读本地 config。
+  if (args['cloud'] && args['agent-id']) {
+    if (!args['agent'] || !VALID_AGENTS.includes(args['agent'])) {
+      errorBox([
+        'ERROR: --cloud --agent-id=<id> 必须同时显式指定 --agent=<type>',
+        '',
+        '云端 sandbox 无本地 config.json，无法自动推断 framework。',
+        `请拼成：npx coze_lab --cloud --agent-id=${args['agent-id']} --agent=claude-code|codex|openclaw`,
+      ]);
+    }
+    return {
+      agent: args['agent'],
+      agentId: args['agent-id'],
+      // 云端 claude-code 配置写进 agent workspace，缺省按约定路径推断（见 main）。
+      workspace: args['workspace'] || '',
+      'codex-home': args['codex-home'],
+      pairCode: args['pair-code'],
+      cloud: true,
+    };
+  }
 
-  // 优先 --agent-id：读 ~/.coze/agents/<id>/config.json 的 framework 自动路由。
+  // 本地 --agent-id：读 ~/.coze/agents/<id>/config.json 的 framework 自动路由。
   if (args['agent-id']) {
     const resolved = resolveAgent(args['agent-id']);
     return {
@@ -4167,6 +4223,8 @@ function validateArgs(args) {
       workspace: resolved.workspace,
       agentRoot: resolved.root,
       'codex-home': args['codex-home'],
+      pairCode: args['pair-code'],
+      cloud: !!args['cloud'],
     };
   }
 
@@ -4183,6 +4241,8 @@ function validateArgs(args) {
       '  --login    Login (Device Code flow)',
       '  --refresh  Force refresh access token',
       '  --logout   Clear cached credentials',
+      '  --verify   Send a test trace to verify the reporting pipeline',
+      '             可带 --pair-code=<值> 写入 trace metadata（缺省自动生成），供查询方回查',
     ]);
   }
   if (!VALID_AGENTS.includes(args['agent'])) {
@@ -4195,7 +4255,7 @@ function validateArgs(args) {
       '  --agent=openclaw',
     ]);
   }
-  return { agent: args['agent'], 'codex-home': args['codex-home'] };
+  return { agent: args['agent'], 'codex-home': args['codex-home'], pairCode: args['pair-code'], cloud: !!args['cloud'] };
 }
 
 // ─── 4. Agent detection ──────────────────────────────────────────────────────
@@ -4341,7 +4401,7 @@ function checkVersionWhitelist(agent, version) {
     'Trace reporting may not work correctly.',
     'Please upgrade and re-run:',
     `  ${UPGRADE_CMD[agent]}`,
-    `  npx @cozeloop/onboard --agent=${agent} ...`,
+    `  npx coze_lab --agent=${agent} ...`,
   ]);
 }
 
@@ -4386,7 +4446,9 @@ function mergeJson(filepath, mergeFn) {
 // writeClaudeCodeHook 配置 Claude Code 的 hook。
 // configBaseDir 缺省 process.cwd()（全局/项目级）；传入 agent 的 workspace 则 per-agent：
 // settings.json + 凭证写进 <configBaseDir>/.claude，仅该 agent（以此为 cwd 启动）生效。
-function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir) {
+// 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');
   const baseDir     = configBaseDir || process.cwd();
@@ -4439,7 +4501,13 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir) {
   const localSettings = mergeJson(localSettingsPath, (existing) => {
     if (!existing.env) existing.env = {};
     existing.env.COZELOOP_WORKSPACE_ID = workspaceId;
-    existing.env.COZELOOP_API_TOKEN    = patToken;
+    // 云端：token 由 sandbox 注入到环境变量 COZE_API_TOKEN，hook 运行时直接读，
+    // 不在配置文件落明文 token。本地：写入 OAuth 拿到的 token。
+    if (cloud) {
+      delete existing.env.COZELOOP_API_TOKEN;
+    } else {
+      existing.env.COZELOOP_API_TOKEN = patToken;
+    }
     // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
     existing.env.x_tt_env  = PPE_TT_ENV;
     existing.env.x_use_ppe = PPE_USE_PPE;
@@ -4458,7 +4526,9 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir) {
 
 // writeCodexHook 把 hook 写进指定的 CODEX_HOME。codexHome 缺省 ~/.codex；
 // 传入动态目录（如 coze-bridge 的 /tmp/coze-bridge-codex-home-xxx）即可 per-agent 生效。
-function writeCodexHook(token, workspaceId, pythonCmd, codexHome) {
+// cloud=true 时 cozeloop.env 不写死 token —— 云端 hook 运行时直接读环境变量
+// COZE_API_TOKEN（见 scripts/codex/cozeloop_hook.py 的 get_fresh_token）。
+function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
   const home       = codexHome || path.join(os.homedir(), '.codex');
   const hooksDir   = path.join(home, 'hooks');
   const hookScript = path.join(hooksDir, 'cozeloop_hook.py');
@@ -4473,14 +4543,18 @@ function writeCodexHook(token, workspaceId, pythonCmd, codexHome) {
   writeHookScript(refreshScript, readScript('shared/cozeloop_refresh.py'));
 
   // 2. Write env file with chmod 600
-  const envContent = [
+  //    云端（cloud）：不落明文 token，hook 运行时从环境变量 COZE_API_TOKEN 读取。
+  const envLines = [
     `COZELOOP_WORKSPACE_ID=${workspaceId}`,
-    `COZELOOP_API_TOKEN=${token}`,
-    'TRACE_TO_COZELOOP=true',
-    // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
-    `x_tt_env=${PPE_TT_ENV}`,
-    `x_use_ppe=${PPE_USE_PPE}`,
-  ].join('\n') + '\n';
+  ];
+  if (!cloud) {
+    envLines.push(`COZELOOP_API_TOKEN=${token}`);
+  }
+  envLines.push('TRACE_TO_COZELOOP=true');
+  // PPE 泳道：cozeloop SDK 读这两个环境变量，自动注入 x-tt-env / x-use-ppe header
+  envLines.push(`x_tt_env=${PPE_TT_ENV}`);
+  envLines.push(`x_use_ppe=${PPE_USE_PPE}`);
+  const envContent = envLines.join('\n') + '\n';
   try {
     fs.writeFileSync(envFile, envContent, { mode: 0o600 });
   } catch (e) {
@@ -4518,12 +4592,16 @@ function writeCodexHook(token, workspaceId, pythonCmd, codexHome) {
     errorBox([`ERROR: Cannot write ${hooksJson}`, '', e.message]);
   }
   ok(`Hook registered in ${hooksJson}`);
-  warn('Codex hook trust: 首次运行 Codex 时会提示信任 hook，请选择"信任"以启用 trace 上报。');
+  warn('Codex hook trust: 首次启动 Codex 会提示 "Hooks need review"。在该提示按 t（Trust all and continue），或在会话内运行 /hooks 后按 t，即可一次性信任全部 hook 启用 trace 上报。');
 
   return { hookScript, envFile, hooksJson };
 }
 
-function writeOpenClawHook(token, workspaceId) {
+// writeOpenClawHook 配置 OpenClaw 的 cozeloop-trace 插件（全局装在 ~/.openclaw）。
+// agentId 非空时并入 plugins.entries[...].config.traceAgentIds allowlist —— 插件运行时
+// 用 resolveAgentIdFromHookCtx 取当前 agentId，仅 allowlist 内的 agent 才上报 trace。
+// allowlist 为空（本地全局模式）= 全部放行，向后兼容。
+function writeOpenClawHook(token, workspaceId, agentId) {
   const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
   const pluginDir  = path.join(os.homedir(), '.cozeloop', 'openclaw-plugin');
 
@@ -4601,12 +4679,25 @@ function writeOpenClawHook(token, workspaceId) {
     existing.plugins.entries[PLUGIN].enabled = true;
     // hooks.allowConversationAccess required for 2026.5+ to access session content
     existing.plugins.entries[PLUGIN].hooks = { allowConversationAccess: true };
-    existing.plugins.entries[PLUGIN].config = {
-      authorization: `Bearer ${token}`,
-      endpoint:      'https://api.coze.cn/v1/loop/opentelemetry',
-      workspaceId,
-      debug:         true,
-    };
+    if (!existing.plugins.entries[PLUGIN].config) existing.plugins.entries[PLUGIN].config = {};
+    const pcfg = existing.plugins.entries[PLUGIN].config;
+    pcfg.authorization = `Bearer ${token}`;
+    pcfg.endpoint      = 'https://api.coze.cn/v1/loop/opentelemetry';
+    pcfg.workspaceId   = workspaceId;
+    pcfg.debug         = true;
+    // per-agent trace 放行：把当前 agentId 并入 traceAgentIds（去重、归一为小写，
+    // 与插件侧 resolveAgentIdFromHookCtx 的归一一致）。无 agentId（全局模式）则不动
+    // allowlist —— 空 allowlist 表示全部放行。
+    if (agentId) {
+      const norm = String(agentId).trim().toLowerCase();
+      // 读 existing 时一并归一（小写、去空），与插件侧 resolveAgentIdFromHookCtx 一致，
+      // 防手工编辑混入大写条目导致去重失效。
+      const list = (Array.isArray(pcfg.traceAgentIds) ? pcfg.traceAgentIds : [])
+        .map((s) => String(s).trim().toLowerCase())
+        .filter(Boolean);
+      if (norm && !list.includes(norm)) list.push(norm);
+      pcfg.traceAgentIds = list;
+    }
     return existing;
   });
 
@@ -4632,15 +4723,17 @@ function writeOpenClawHook(token, workspaceId) {
 
 // ─── 8. Auth — Device Code OAuth + token store ───────────────────────────────
 const https = require('https');
+const crypto = require('crypto');
 
-function httpsPost(url, body) {
+function httpsPost(url, body, extraHeaders) {
   return new Promise((resolve, reject) => {
     const data = JSON.stringify(body);
     const u = new URL(url);
     const req = https.request(
       { hostname: u.hostname, path: u.pathname + u.search, method: 'POST',
         headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data),
-                   'x-tt-env': PPE_TT_ENV, 'x-use-ppe': PPE_USE_PPE } },
+                   'x-tt-env': PPE_TT_ENV, 'x-use-ppe': PPE_USE_PPE,
+                   ...(extraHeaders || {}) } },
       (res) => {
         let buf = '';
         res.on('data', c => buf += c);
@@ -4654,6 +4747,66 @@ function httpsPost(url, body) {
   });
 }
 
+// 真实发一条最小 OTLP trace 到 CozeLoop，验证上报链路是否打通。
+// 只看 HTTP 状态码（2xx=通），不回查 trace 是否落库——回查由外部查询方完成。
+// pairCode 写进 span 的 pair_code attribute，供查询方按该字段过滤回查；缺省自动生成。
+// 不在函数内退出，退出行为交给调用方（主流程 Step 6 / 独立命令 --verify）。
+async function verifyTraceReport(token, workspaceId, pairCode) {
+  const traceId = crypto.randomBytes(16).toString('hex'); // 32 hex chars
+  const spanId  = crypto.randomBytes(8).toString('hex');  // 16 hex chars
+  const nowNs   = String(Date.now() * 1_000_000);         // OTLP 要求纳秒 unix 时间（字符串）
+  // 缺省自动生成 12 位 hex 配对码；查询方按 field_name="pair_code" 回查。
+  const pair    = pairCode || crypto.randomBytes(6).toString('hex');
+
+  const otlpBody = {
+    resourceSpans: [{
+      resource: {
+        attributes: [
+          { key: 'service.name', value: { stringValue: 'cozelab-onboard' } },
+        ],
+      },
+      scopeSpans: [{
+        scope: { name: 'cozelab-onboard-selfcheck' },
+        spans: [{
+          traceId,
+          spanId,
+          name: 'cozelab-onboard-selfcheck',
+          kind: 1,
+          startTimeUnixNano: nowNs,
+          endTimeUnixNano: nowNs,
+          status: { code: 1 },
+          attributes: [
+            { key: 'pair_code', value: { stringValue: pair } },
+          ],
+        }],
+      }],
+    }],
+  };
+
+  let res;
+  try {
+    res = await httpsPost(
+      `${COZE_API}/v1/loop/opentelemetry/v1/traces`,
+      otlpBody,
+      { Authorization: `Bearer ${token}`, 'cozeloop-workspace-id': workspaceId },
+    );
+  } catch (e) {
+    warn(`trace 上报失败: ${e.message}`);
+    return { success: false, status: 0, body: e.message, traceId, pairCode: pair };
+  }
+
+  const success = res.status >= 200 && res.status < 300;
+  if (success) {
+    ok(`trace 上报成功 (traceId=${traceId}, pair_code=${pair})`);
+    info(`查询方可用 pair_code=${pair} 在 CozeLoop 回查确认该 trace 已落库。`);
+  } else {
+    warn(`trace 上报失败: HTTP ${res.status}`);
+    const snippet = (res.body || '').slice(0, 300);
+    if (snippet) console.log(snippet);
+  }
+  return { success, status: res.status, body: res.body, traceId, pairCode: pair };
+}
+
 function httpsGet(url, headers) {
   return new Promise((resolve, reject) => {
     // 合并 PPE 泳道 header
@@ -4911,21 +5064,10 @@ function authStatus() {
   box(lines, statusColor);
 }
 
-// ── Verify token is usable ────────────────────────────────────────────────
-async function verifyWorkspace(token) {
-  info('验证 Token 有效性...');
-  // Token validity is guaranteed by the Device Code OAuth flow.
-  // We skip a separate API call here since the OAuth app may not have
-  // Account.listWorkspace permission — the token itself is the proof.
-  if (!token) return null;
-  ok(`Token 有效，工作空间 ${WORKSPACE_ID} 确认。`);
-  return token;
-}
-
 // ─── 9. Main ─────────────────────────────────────────────────────────────────
 const NEXT_STEP = {
-  'claude-code': 'Hook 已写入。请在当前 Claude Code 会话运行 /new（或重开会话）使 hook 生效——外部进程无法替你 /new。',
-  'codex':       'Hook 已写入。请重开 Codex 会话使 hook 生效——外部进程无法替你重启当前会话。',
+  'claude-code': 'Hook 已写入。Claude Code 会自动热重载 hooks，当前会话即刻生效，无需 /new 或重启。',
+  'codex':       'Hook 已写入。Codex 在会话启动时加载 hook，当前会话不会即时生效；请重开 Codex 会话（已配置 SessionStart hook，新会话自动加载）。',
   'openclaw':    'OpenClaw gateway 已自动重启，trace 即刻生效。',
 };
 
@@ -4991,41 +5133,58 @@ async function main() {
     return;
   }
 
+  if (args.verify) {
+    info('验证 trace 上报链路...');
+    const token = await getValidToken();   // 无凭证会自动走登录/刷新
+    console.log('');
+    const result = await verifyTraceReport(token, WORKSPACE_ID, args.pairCode);
+    process.exit(result.success ? 0 : 1);
+  }
+
   const { agent } = args;
+  // 云端模式：开启结构化输出 + errorBox 抛异常（而非 exit）。
+  CLOUD_MODE = !!args.cloud;
+  // per-agent 路由时 agent 的 workspace（claude-code 用它做配置根目录）。
   // per-agent 路由时 agent 的 workspace（claude-code 用它做配置根目录）。
-  const agentWorkspace = args.workspace || '';
+  // 云端 claude-code 未显式传 workspace 时，按约定路径 ~/.coze/agents/<id>/workspace 推断。
+  let agentWorkspace = args.workspace || '';
+  if (args.cloud && args.agentId && agent === 'claude-code' && !agentWorkspace) {
+    agentWorkspace = path.join(os.homedir(), '.coze', 'agents', args.agentId, 'workspace');
+  }
   if (args.agentId) {
     info(`目标 agent: ${args.agentId} (framework=${agent}, workspace=${agentWorkspace || 'N/A'})`);
     console.log('');
   }
 
-  // Step 1: Authorize (load cached → refresh → device code)
-  info('Step 1/5: 检查授权状态...');
-  let token = await getValidToken();
-  console.log('');
-
-  // Step 2: Verify token works
-  info('Step 2/5: 验证工作空间权限...');
-  let verified = await verifyWorkspace(token);
-  if (verified === null) {
-    warn('Token 已失效，正在重新授权...');
-    deleteCredentials();
-    console.log('');
-    token = await deviceCodeAuth().then(c => c.access_token);
-    verified = await verifyWorkspace(token);
-    if (verified === null) {
-      errorBox(['ERROR: 重新授权后 Token 仍无效，请联系管理员。']);
+  // Step 1: Authorize.
+  //   云端（--cloud）：token 取自环境变量 COZE_API_TOKEN，跳过 OAuth / credentials.json。
+  //   本地：load cached → refresh → device code。
+  let token;
+  if (args.cloud) {
+    info('Step 1/5: 云端模式，从环境变量 COZE_API_TOKEN 读取 token...');
+    token = process.env.COZE_API_TOKEN;
+    if (!token) {
+      errorBox([
+        'ERROR: --cloud 模式要求环境变量 COZE_API_TOKEN',
+        '',
+        '云端 sandbox 应在进程环境中注入 COZE_API_TOKEN。',
+        '未检测到该变量，无法配置 trace 上报。',
+      ]);
     }
+    ok('已从环境变量读取 COZE_API_TOKEN');
+  } else {
+    info('Step 1/5: 检查授权状态...');
+    token = await getValidToken();
   }
   console.log('');
 
-  // Step 3: Detect agent binary
-  info('Step 3/5: Detecting agent...');
+  // Step 2: Detect agent binary
+  info('Step 2/5: Detecting agent...');
   const version = detectAgent(agent);
   console.log('');
 
-  // Step 4: Environment checks
-  info('Step 4/5: Checking environment...');
+  // Step 3: Environment checks
+  info('Step 3/5: Checking environment...');
   let pythonCmd = null;
   if (agent !== 'openclaw') {
     pythonCmd = checkPython();
@@ -5034,20 +5193,33 @@ async function main() {
   checkVersionWhitelist(agent, version);
   console.log('');
 
-  // Step 5: Write hook configuration
-  info('Step 5/5: Writing hook configuration...');
+  // Step 4: Write hook configuration
+  info('Step 4/5: Writing hook configuration...');
   let written = {};
   if (agent === 'claude-code') {
     // per-agent 路由时把配置写进 agent 的 workspace（仅该 agent 生效）。
-    written = writeClaudeCodeHook(token, WORKSPACE_ID, pythonCmd, args.agentId ? agentWorkspace : undefined);
+    // 云端按 agentId 路由但 workspace 为空会导致 settings.json 落 ~/.claude、
+    // settings.local.json 落进程 cwd —— per-agent 隔离失效。此时显式报错。
+    if (args.agentId && !agentWorkspace) {
+      errorBox([
+        `ERROR: agent "${args.agentId}" 的 config.json 缺少 workspace 字段`,
+        '',
+        'claude-code per-agent 配置需要明确的 workspace 目录，',
+        '否则 hook 配置会落到全局/进程目录，无法做到 per-agent 隔离。',
+      ]);
+    }
+    written = writeClaudeCodeHook(token, WORKSPACE_ID, pythonCmd, args.agentId ? agentWorkspace : undefined, args.cloud);
   } else if (agent === 'codex') {
     // CODEX_HOME 来源优先级：--codex-home= > 环境变量 CODEX_HOME > ~/.codex（缺省）。
     const codexHome = args['codex-home'] || process.env.CODEX_HOME || undefined;
     if (codexHome) info(`Codex 配置目录: ${codexHome}`);
-    written = writeCodexHook(token, WORKSPACE_ID, pythonCmd, codexHome);
+    written = writeCodexHook(token, WORKSPACE_ID, pythonCmd, codexHome, args.cloud);
   } else {
-    written = writeOpenClawHook(token, WORKSPACE_ID) || {};
+    // openclaw：云端用 traceAgentIds allowlist 做 per-agent 放行。
+    written = writeOpenClawHook(token, WORKSPACE_ID, args.agentId) || {};
   }
+  // 走到这里说明 detectAgent / 环境检查 / 写 hook 配置全部成功 → 注入成功。
+  cloudResult.inject = 'ok';
   console.log('');
 
   // Success summary（用实际写入路径，per-agent / 自定义 CODEX_HOME 时也准确）
@@ -5079,9 +5251,52 @@ async function main() {
   info('确保 CozeLoop Token 具备 Trace ingest 权限，否则 hook 触发但上报会失败。');
   console.log('');
 
+  // Step 5: Verify trace reporting end-to-end
+  info('Step 5/5: 验证 trace 上报链路...');
+  const verifyResult = await verifyTraceReport(token, WORKSPACE_ID, args.pairCode);
+  if (verifyResult.success) {
+    cloudResult.verify = 'ok';
+  } else if (CLOUD_MODE) {
+    // 云端：注入已成功，验证失败不阻断（放行），记录结果供后台弹 warning。
+    cloudResult.verify = 'fail';
+    cloudResult.logid = extractLogid(verifyResult.body) || cloudResult.logid;
+    cloudResult.message = `trace 上报自检失败 HTTP ${verifyResult.status}: ${(verifyResult.body || '').slice(0, 200)}`;
+    warn('trace 上报自检失败，但 hook 配置已写入（云端放行）。');
+    console.log('');
+    emitCloudResult();
+    successBox(summaryLines);
+    return;
+  } else {
+    errorBox([
+      'ERROR: trace 上报自检失败',
+      '',
+      `HTTP ${verifyResult.status}`,
+      (verifyResult.body || '').slice(0, 300),
+      '',
+      'hook 配置已写入，但上报链路未打通。',
+      '请确认 CozeLoop Token 具备 Trace ingest 权限，再重试。',
+    ]);   // errorBox 内部 process.exit(1)
+  }
+  console.log('');
+
+  emitCloudResult();
   successBox(summaryLines);
 }
 
 main().catch(e => {
+  // 云端模式：失败时输出结构化结果（含 logid），exit 非 0 但带 COZE_LAB_RESULT 行。
+  if (CLOUD_MODE) {
+    if (cloudResult.inject !== 'ok') {
+      // 写 hook 配置前的任何失败 → 注入失败。
+      cloudResult.inject = 'fail';
+    } else if (cloudResult.verify === 'skip') {
+      // 注入已成功，但验证阶段异常崩溃（未走到正常的 ok/fail 判定）→ 记为验证失败。
+      cloudResult.verify = 'fail';
+    }
+    if (!cloudResult.message) cloudResult.message = e && e.message ? e.message : 'unexpected failure';
+    if (!cloudResult.logid) cloudResult.logid = extractLogid(cloudResult.message);
+    emitCloudResult();
+    process.exit(1);
+  }
   errorBox(['ERROR: Unexpected failure', '', e.message]);
 });

package/package.json

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

package/scripts/claude-code/cozeloop_hook.py

@@ -45,7 +45,7 @@ DEBUG = os.environ.get("CC_COZELOOP_DEBUG", "").lower() == "true"
 _COZELOOP_CLIENT_ID = "46371084383473718052118955183420.app.coze"
 _COZE_API = "https://api.coze.cn"
 _REFRESH_THRESHOLD = 10 * 60  # refresh when < 10 minutes remain
-_DEFAULT_WORKSPACE_ID = "7645949103524380682"  # hardcoded spaceID fallback
+_DEFAULT_WORKSPACE_ID = "7644910356078837760"  # hardcoded spaceID fallback
 
 
 # --- coze-context parsing -------------------------------------------------
@@ -224,7 +224,8 @@ def get_fresh_token() -> Optional[str]:
             if new_token:
                 return new_token
             debug_log("Refresh failed, falling back to env var.")
-    return os.environ.get("COZELOOP_API_TOKEN")
+    # 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")
 
 # -------------------------------------------------------------------------
 

package/scripts/codex/cozeloop_hook.py

@@ -45,7 +45,7 @@ from typing import Optional, List, Dict, Any
 _COZELOOP_CLIENT_ID = "46371084383473718052118955183420.app.coze"
 _COZE_API = "https://api.coze.cn"
 _REFRESH_THRESHOLD = 10 * 60
-_DEFAULT_WORKSPACE_ID = "7645949103524380682"  # hardcoded spaceID fallback
+_DEFAULT_WORKSPACE_ID = "7644910356078837760"  # hardcoded spaceID fallback
 
 
 # --- coze-context parsing -------------------------------------------------
@@ -197,7 +197,8 @@ def get_fresh_token():
             new_token = _refresh_token(creds["refresh_token"])
             if new_token:
                 return new_token
-    return os.environ.get("COZELOOP_API_TOKEN")
+    # 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")
 # -------------------------------------------------------------------------
 
 # --- SDK Import ---