@lawrenceliang-btc/atel-sdk 1.1.8 → 1.1.10

package/README.md

@@ -21,6 +21,10 @@ ATEL provides the cryptographic primitives and protocol building blocks that ena
 - ATEL handles DID identity, relay, inbox, callback, notification, and paid order state
 - OpenClaw or your own runtime handles reasoning and tool use
 - Cross-platform CLI (Linux/macOS/Windows)
+- Paid Platform orders currently support two settlement chains:
+  - `Base`
+  - `BSC`
+- For paid orders, the chain truth source is always `order.chain`
 
 ### P2P Friend System
 - Relationship-based access control (friends-only mode)
@@ -59,6 +63,14 @@ atel register "My Agent" "assistant,research"
 atel start 3100
 ```
 
+If you want to support paid Platform orders on EVM chains, configure at least one paid-order chain key before or after registering:
+
+```bash
+export ATEL_BASE_PRIVATE_KEY=...
+# or
+export ATEL_BSC_PRIVATE_KEY=...
+```
+
 ### Recommended Runtime
 
 ATEL is not a built-in general-purpose LLM executor. The recommended setup is:
@@ -76,6 +88,8 @@ atel start 3100
 
 For custom runtimes, point `ATEL_EXECUTOR_URL` at your own service.
 
+For paid orders, do not hardcode Base as the only chain. Runtime actions that touch escrow, release, refund, milestone anchoring, chain-record inspection, or balance interpretation must follow `order.chain`.
+
 ## Architecture
 
 ATEL is organized into protocol and runtime layers:
@@ -170,6 +184,17 @@ atel milestone-submit <orderId> <index> --result  # Submit milestone result
 atel milestone-verify <orderId> <index> --pass    # Verify submitted milestone
 ```
 
+Notes:
+
+- Paid Platform orders are currently supported on `Base` and `BSC`
+- Before acting on a paid order, inspect `atel order-info <orderId>` or `atel milestone-status <orderId>`
+- Treat `order.chain` as the only source of truth for:
+  - smart wallet
+  - escrow
+  - release / refund
+  - chain-records
+  - chain-side balance interpretation
+
 ## API Examples
 
 ### Identity & Signing

package/bin/atel.mjs

@@ -52,7 +52,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import crypto from 'node:crypto';
 import {
   AgentIdentity, AgentEndpoint, AgentClient, HandshakeManager,
@@ -91,6 +91,7 @@ const NOTIFY_TARGETS_FILE = resolve(ATEL_DIR, 'notify-targets.json');
 const TRADE_TRACK_FILE = resolve(ATEL_DIR, 'tracked-orders.json');
 const P2P_STATUS_FILE = resolve(ATEL_DIR, 'p2p-task-status.jsonl');
 const PENDING_AGENT_CALLBACKS_FILE = resolve(ATEL_DIR, 'pending-agent-callbacks.json');
+const ORDER_WORK_DIR = resolve(ATEL_DIR, 'order-workspaces');
 const KEYS_DIR = resolve(ATEL_DIR, 'keys');
 const ANCHOR_FILE = resolve(KEYS_DIR, 'anchor.json');
 
@@ -100,6 +101,111 @@ const DEFAULT_POLICY = { rateLimit: 60, maxPayloadBytes: 1048576, maxConcurrent:
 
 function ensureDir() { if (!existsSync(ATEL_DIR)) mkdirSync(ATEL_DIR, { recursive: true }); }
 
+function ensureOrderWorkspace(orderId, context = {}) {
+  ensureDir();
+  const safeOrderId = String(orderId || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_');
+  const dir = resolve(ORDER_WORK_DIR, safeOrderId);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const contextFile = join(dir, 'ORDER_CONTEXT.md');
+  const lines = [
+    `# ATEL Order Context`,
+    ``,
+    `Order ID: ${orderId || ''}`,
+    `Chain: ${context.chain || ''}`,
+    `Role: ${context.role || ''}`,
+    `Status: ${context.status || ''}`,
+    `Phase: ${context.phase || ''}`,
+    `Current Milestone: ${context.currentMilestone ?? ''}`,
+    `Milestone Title: ${context.milestoneTitle || ''}`,
+    ``,
+    `## Order Description`,
+    context.orderDescription || '',
+    ``,
+    `## Milestone Objective`,
+    context.milestoneObjective || '',
+    ``,
+    `## Submission Content`,
+    context.resultSummary || '',
+    ``,
+    `## Previous Approved Outputs`,
+    context.previousApprovedOutputs || '',
+    ``,
+    `## Hard Rules`,
+    `- Only work from the order description and milestone objective in this file.`,
+    `- Do not inspect unrelated local projects or repository content unless the order explicitly asks for repo analysis.`,
+    `- Do not infer a different project from stray files in the machine workspace.`,
+    `- Return only content that directly satisfies this order.`,
+    ``,
+  ];
+  writeFileSync(contextFile, lines.join('\n'));
+  return { dir, contextFile };
+}
+
+function getOrderWorkspace(orderId, context = {}) {
+  if (!orderId) return { dir: process.cwd(), contextFile: '' };
+  return ensureOrderWorkspace(orderId, context);
+}
+
+function getAtelWorkspaceRoot() {
+  return dirname(ATEL_DIR);
+}
+
+function shouldAllowRepoAccess(context = {}) {
+  const description = String(context?.orderDescription || '').toLowerCase();
+  const objective = String(context?.milestoneObjective || '').toLowerCase();
+  const resultSummary = String(context?.resultSummary || '').toLowerCase();
+  const previousApprovedOutputs = String(context?.previousApprovedOutputs || '').toLowerCase();
+  const combined = `${description}\n${objective}\n${resultSummary}\n${previousApprovedOutputs}`;
+  return /(repo|repository|codebase|仓库|代码库|项目代码|source code|read files|analyze code|修改代码|修复代码|实现功能)/i.test(combined);
+}
+
+function summarizeApprovedMilestones(milestones = [], beforeIndex = Number.MAX_SAFE_INTEGER) {
+  return (Array.isArray(milestones) ? milestones : [])
+    .filter((m) => m && m.status === 'verified' && Number.isFinite(m.index) && m.index < beforeIndex)
+    .sort((a, b) => a.index - b.index)
+    .map((m) => `M${m.index}: ${m.title || ''}\nResult: ${m.resultSummary || ''}`.trim())
+    .join('\n\n');
+}
+
+function sanitizeAgentPrompt(promptText, meta = {}) {
+  const raw = typeof promptText === 'string' ? promptText : '';
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    log({ event: 'agent_prompt_skip_empty', eventType: meta.eventType || 'unknown', dedupeKey: meta.dedupeKey || '' });
+    return '';
+  }
+
+  // Keep a large but bounded margin below upstream model limits. We only need
+  // concise task prompts here; oversized prompts add noise and can trigger
+  // upstream length validation errors.
+  const maxChars = 16000;
+  if (trimmed.length <= maxChars) return trimmed;
+
+  const truncated = `${trimmed.slice(0, maxChars)}\n\n[Prompt truncated by ATEL SDK to stay within model input limits.]`;
+  log({
+    event: 'agent_prompt_truncated',
+    eventType: meta.eventType || 'unknown',
+    dedupeKey: meta.dedupeKey || '',
+    originalChars: trimmed.length,
+    finalChars: truncated.length,
+  });
+  return truncated;
+}
+
+function isKnownUpstreamModelInputError(text) {
+  const value = String(text || '');
+  return value.includes('InternalError.Algo.InvalidParameter')
+    || value.includes('Range of input length should be [1, 258048]');
+}
+
+function summarizeAgentOutput(text, maxChars = 300) {
+  const raw = String(text || '');
+  const trimmed = raw.trim();
+  if (!trimmed) return '';
+  if (isKnownUpstreamModelInputError(trimmed)) return '[suppressed upstream model input-length error]';
+  return trimmed.substring(0, maxChars);
+}
+
 // ═══════════════════════════════════════════════════════════════════
 // Notification Target System — auto-discover gateway, manage targets
 // ═══════════════════════════════════════════════════════════════════
@@ -348,6 +454,18 @@ async function executeRecommendedActionDirect(eventType, action, cwd, dedupeKey)
   if (command.length === 0) {
     return { ok: false, skipped: true, reason: 'empty_command' };
   }
+  const actionKey = JSON.stringify(command);
+  if (globalThis.__atelActiveDirectActionKeys?.has(actionKey)) {
+    log({
+      event: 'recommended_action_direct_skip',
+      eventType,
+      dedupeKey,
+      action: action.action,
+      command,
+      reason: 'inflight_duplicate',
+    });
+    return { ok: true, skipped: true, reason: 'inflight_duplicate' };
+  }
 
   // Idempotency guard: short-circuit duplicate milestone plan/submit/verify actions
   // if the order or milestone has already advanced past the required state.
@@ -384,8 +502,10 @@ async function executeRecommendedActionDirect(eventType, action, cwd, dedupeKey)
           }
           const milestone = needsMilestoneIndex && Array.isArray(state?.milestones) ? state.milestones.find((m) => m.index === index) : null;
           if (needsMilestoneIndex && milestone) {
-            const expectedStatus = command[1] === 'milestone-verify' ? 'submitted' : 'pending';
-            if (milestone.status !== expectedStatus) {
+            const expectedStatuses = command[1] === 'milestone-verify'
+              ? ['submitted']
+              : (eventType === 'milestone_rejected' ? ['pending', 'rejected'] : ['pending']);
+            if (!expectedStatuses.includes(milestone.status)) {
               log({
                 event: 'recommended_action_direct_skip',
                 eventType,
@@ -414,12 +534,68 @@ async function executeRecommendedActionDirect(eventType, action, cwd, dedupeKey)
   const { execFile } = await import('child_process');
   const childCmd = command[0] === 'atel' ? process.execPath : command[0];
   const childArgs = command[0] === 'atel' ? [process.argv[1], ...command.slice(1)] : command.slice(1);
+  const childCwd = command[0] === 'atel' ? getAtelWorkspaceRoot() : cwd;
 
   log({ event: 'recommended_action_direct_trigger', eventType, dedupeKey, action: action.action, command });
+  globalThis.__atelActiveDirectActionKeys ??= new Set();
+  globalThis.__atelActiveDirectActionKeys.add(actionKey);
 
   return await new Promise((resolve) => {
-    execFile(childCmd, childArgs, { timeout: 180000, cwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+    execFile(childCmd, childArgs, { timeout: 180000, cwd: childCwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      globalThis.__atelActiveDirectActionKeys?.delete(actionKey);
       if (err) {
+        const combinedErrorText = String(stderr || err.message || '');
+        if (
+          command[0] === 'atel' &&
+          command[1] === 'milestone-feedback' &&
+          command.includes('--approve') &&
+          combinedErrorText.includes('order not in milestone_review status')
+        ) {
+          log({
+            event: 'recommended_action_direct_skip',
+            eventType,
+            dedupeKey,
+            action: action.action,
+            command,
+            reason: 'order_status_executing',
+          });
+          resolve({ ok: true, skipped: true, reason: 'order_status_executing' });
+          return;
+        }
+        if (
+          command[0] === 'atel' &&
+          command[1] === 'milestone-submit' &&
+          combinedErrorText.includes('milestone cannot be submitted in status: submitted')
+        ) {
+          log({
+            event: 'recommended_action_direct_skip',
+            eventType,
+            dedupeKey,
+            action: action.action,
+            command,
+            reason: 'milestone_status_submitted',
+          });
+          resolve({ ok: true, skipped: true, reason: 'milestone_status_submitted' });
+          return;
+        }
+        if (
+          command[0] === 'atel' &&
+          command[1] === 'milestone-verify' &&
+          (combinedErrorText.includes('milestone cannot be verified in status: verified') ||
+           combinedErrorText.includes('milestone not in submitted status') ||
+           combinedErrorText.includes('milestone cannot be verified in status: settled'))
+        ) {
+          log({
+            event: 'recommended_action_direct_skip',
+            eventType,
+            dedupeKey,
+            action: action.action,
+            command,
+            reason: 'milestone_already_processed',
+          });
+          resolve({ ok: true, skipped: true, reason: 'milestone_already_processed' });
+          return;
+        }
         log({
           event: 'recommended_action_direct_error',
           eventType,
@@ -439,7 +615,7 @@ async function executeRecommendedActionDirect(eventType, action, cwd, dedupeKey)
         dedupeKey,
         action: action.action,
         command,
-        stdout: (stdout || '').substring(0, 400),
+        stdout: summarizeAgentOutput(stdout, 400),
       });
       resolve({ ok: true, stdout });
     });
@@ -2574,7 +2750,9 @@ async function cmdStart(port) {
           return;
         }
       }
-      res.status(404).json({ error: 'Unknown dedupeKey' });
+      // Treat late/duplicate/expired callbacks as idempotent skips rather than hard errors.
+      // The callback source has already completed, timed out, or been recovered elsewhere.
+      res.json({ status: 'ok', skipped: true, reason: 'unknown_or_expired_dedupeKey' });
       return;
     }
     log({
@@ -2588,6 +2766,67 @@ async function cmdStart(port) {
     });
 
     if (body.status === 'failed') {
+      // Some subagents pessimistically send `failed` after already producing a usable
+      // summary/result because they observed a callback transport error on their side.
+      // If the payload is still actionable, recover it here instead of dropping the flow.
+      const failedAction = buildAgentCallbackAction(pending.eventType, pending.payload || {}, body);
+      if (failedAction.ok && !failedAction.skipped) {
+        log({
+          event: 'agent_callback_failed_recovered',
+          eventType: pending.eventType,
+          dedupeKey,
+          childSessionKey: pending.childSessionKey,
+          summary: body.summary,
+          error: body.error,
+        });
+
+        if (failedAction.action?.type === 'local_result') {
+          try {
+            const localResp = await fetch(`http://127.0.0.1:${p}/atel/v1/result`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                taskId: failedAction.action.taskId,
+                result: failedAction.action.result,
+                success: true,
+              }),
+              signal: AbortSignal.timeout(15000),
+            });
+            const localBody = await localResp.json().catch(() => ({}));
+            pendingAgentCallbacks.delete(dedupeKey);
+            if (localResp.ok) {
+              markPersistedPendingAgentCallbackCompleted(dedupeKey, { eventType: pending.eventType, payload: pending.payload, cwd: pending.cwd, source: dedupeKey?.startsWith('reconcile:') ? 'reconcile' : 'main', action: failedAction.action, localBody, recoveredFromFailed: true });
+              pending.resolve({ ok: true, recovered: true, body, action: failedAction.action, localBody });
+              res.json({ status: 'ok', recovered: true });
+              return;
+            }
+            clearPersistedPendingAgentCallback(dedupeKey);
+            pending.resolve({ ok: false, body, action: failedAction.action, localBody, error: localBody.error || 'local_result_callback_failed' });
+            res.status(500).json({ error: localBody.error || 'local_result_callback_failed' });
+            return;
+          } catch (e) {
+            pendingAgentCallbacks.delete(dedupeKey);
+            clearPersistedPendingAgentCallback(dedupeKey);
+            pending.resolve({ ok: false, body, action: failedAction.action, error: e.message });
+            res.status(500).json({ error: e.message || 'local_result_callback_failed' });
+            return;
+          }
+        }
+
+        const execResult = await executeRecommendedActionDirect(pending.eventType, failedAction.action, pending.cwd || process.cwd(), dedupeKey);
+        pendingAgentCallbacks.delete(dedupeKey);
+        if (execResult.ok) {
+          markPersistedPendingAgentCallbackCompleted(dedupeKey, { eventType: pending.eventType, payload: pending.payload, cwd: pending.cwd, source: dedupeKey?.startsWith('reconcile:') ? 'reconcile' : 'main', action: failedAction.action, recoveredFromFailed: true });
+          pending.resolve({ ok: true, recovered: true, body, action: failedAction.action, execResult });
+          res.json({ status: 'ok', recovered: true });
+          return;
+        }
+        clearPersistedPendingAgentCallback(dedupeKey);
+        pending.resolve({ ok: false, body, action: failedAction.action, execResult, error: execResult.error || 'callback_action_failed' });
+        res.status(500).json({ error: execResult.error || 'callback_action_failed' });
+        return;
+      }
+
       pendingAgentCallbacks.delete(dedupeKey);
       clearPersistedPendingAgentCallback(dedupeKey);
       pending.resolve({ ok: false, body, error: body.error || 'agent_reported_failed' });
@@ -2661,7 +2900,7 @@ async function cmdStart(port) {
     res.json({ status: 'ok' });
   });
 
-  function buildGatewayCallbackPrompt(eventType, promptText, callbackUrl, dedupeKey, cwd) {
+  function buildGatewayCallbackPrompt(eventType, promptText, callbackUrl, dedupeKey, cwd, payload = {}) {
     const callbackExamples = {
       milestone_submitted: [
         '通过时执行：',
@@ -2701,18 +2940,30 @@ async function cmdStart(port) {
     ].join('\n');
 
     const callbackDone = eventType === 'milestone_submitted' ? callbackExamples.milestone_submitted : callbackExamples.default;
+    const contextFile = join(cwd, 'ORDER_CONTEXT.md');
+    const allowRepoAccess = shouldAllowRepoAccess(payload);
+    const fileAccessRule = allowRepoAccess
+      ? `3. 仅允许使用目录 ${cwd} 下与当前订单直接相关的内容；如果订单明确要求读仓库，也只能读取该订单工作区中明确提供的路径。`
+      : `3. 本单禁止读取任何本地文件、共享草稿、仓库或其他项目。不要使用文件搜索、目录浏览、读文件等方式扩展上下文；只允许依据本条消息中的订单描述、里程碑目标、提交内容来工作。`;
+    const contextRule = allowRepoAccess
+      ? `4. 优先读取 ${contextFile}，严格以其中的订单描述、里程碑目标、提交内容为准。`
+      : `4. 不要扫描本机其他目录，不要读取 /root/atel-workspace 下的共享文件，不要根据历史项目或 stray files 推断任务。`;
+    const repoRule = allowRepoAccess
+      ? `5. 只有当订单明确要求分析仓库/代码时，才允许读取订单工作区里显式提供的代码路径；禁止顺带读取其他目录。`
+      : `5. 本单不是 repo/code 任务。禁止把任务扩展成代码分析、工程改造或共享草稿筛选。`;
     if (eventType === 'p2p_task') {
       return `${promptText}
 
 重要要求：
 1. 这是一个 P2P 任务。不要调用 atel result；本地 SDK 会在你回调后自动提交结果。
 2. 你的任务是认真完成 AI 工作，并把最终结论通过回调发回本地 SDK。
-3. 你可以在目录 ${cwd} 下阅读文件、运行分析命令、整理内容，但不要自己推进 ATEL 状态机。
-4. 完成后，必须立刻执行下面这个成功回调命令模板，并把其中内容替换成你的真实结果：
+${fileAccessRule}
+${contextRule}
+5. 完成后，必须立刻执行下面这个成功回调命令模板，并把其中内容替换成你的真实结果：
 
 ${callbackDone}
 
-5. 如果重试后仍然失败，也必须执行下面这个失败回调命令：
+6. 如果重试后仍然失败，也必须执行下面这个失败回调命令：
 
 ${callbackFailed}
 `;
@@ -2723,17 +2974,191 @@ ${callbackFailed}
 重要要求：
 1. 不要执行 atel milestone-submit / milestone-verify / milestone-feedback 命令；这些命令会由本地 SDK 在你回调后代为执行。
 2. 你的任务是认真完成 AI 工作，并把最终结论通过回调发回本地 SDK。
-3. 你可以在目录 ${cwd} 下阅读文件、运行分析命令、整理内容，但最终不要自己推进 ATEL 状态机。
-4. 完成后，必须立刻执行下面这个成功回调命令模板，并把其中内容替换成你的真实结果：
+${fileAccessRule}
+${contextRule}
+${repoRule}
+6. 完成后，必须立刻执行下面这个成功回调命令模板，并把其中内容替换成你的真实结果：
 
 ${callbackDone}
 
-5. 如果重试后仍然失败，也必须执行下面这个失败回调命令：
+7. 如果重试后仍然失败，也必须执行下面这个失败回调命令：
 
 ${callbackFailed}
 `;
   }
 
+  function buildLocalAgentPrompt(eventType, promptText) {
+    if (eventType === 'milestone_submitted') {
+      return `${promptText}
+
+重要：你不是在和用户聊天。
+不要输出 markdown、代码块、解释、分析过程。
+你必须只输出一行 JSON。
+
+通过时：
+{"decision":"pass","summary":"简短通过原因"}
+
+拒绝时：
+{"decision":"reject","reason":"具体拒绝原因","summary":"简短审核结论"}`;
+    }
+
+    if (['milestone_plan_confirmed', 'milestone_verified', 'milestone_rejected'].includes(eventType)) {
+      return `${promptText}
+
+重要：你不是在和用户聊天。
+不要输出 markdown、标题、项目符号、解释、分析过程。
+你必须只输出一行 JSON。
+
+格式：
+{"result":"当前里程碑的真实交付内容"}`;
+    }
+
+    return promptText;
+  }
+
+  function normalizeLocalAgentStdout(stdout) {
+    const text = String(stdout || '').trim();
+    if (!text) return '';
+    try {
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed?.payloads)) {
+        for (const item of parsed.payloads) {
+          const candidate = String(item?.text || '').trim();
+          if (candidate) return candidate;
+        }
+      }
+      if (typeof parsed?.text === 'string' && parsed.text.trim()) return parsed.text.trim();
+      if (typeof parsed?.result === 'string' && parsed.result.trim()) return JSON.stringify({ result: parsed.result.trim() });
+      if (typeof parsed?.decision === 'string') return JSON.stringify(parsed);
+    } catch {}
+    const fencedJson = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fencedJson?.[1]) return fencedJson[1].trim();
+    const jsonObjects = text.match(/\{[\s\S]*\}/g);
+    if (jsonObjects?.length) {
+      for (let i = jsonObjects.length - 1; i >= 0; i -= 1) {
+        const candidate = jsonObjects[i].trim();
+        try {
+          const parsed = JSON.parse(candidate);
+          if (Array.isArray(parsed?.payloads)) {
+            for (const item of parsed.payloads) {
+              const nested = String(item?.text || '').trim();
+              if (nested) return nested;
+            }
+          }
+          if (typeof parsed?.text === 'string' && parsed.text.trim()) return parsed.text.trim();
+          if (typeof parsed?.result === 'string' && parsed.result.trim()) return JSON.stringify({ result: parsed.result.trim() });
+          if (typeof parsed?.decision === 'string') return JSON.stringify(parsed);
+          return candidate;
+        } catch {}
+      }
+    }
+    const jsonLines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+    for (let i = jsonLines.length - 1; i >= 0; i -= 1) {
+      const candidate = jsonLines[i];
+      if (!(candidate.startsWith('{') && candidate.endsWith('}'))) continue;
+      try {
+        JSON.parse(candidate);
+        return candidate;
+      } catch {}
+    }
+    return text;
+  }
+
+  function normalizeResult(value) {
+    return String(value || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function sanitizeHookSessionId(value) {
+    const raw = String(value || '').trim();
+    if (!raw) return `atel-hook-${Date.now()}`;
+    const cleaned = raw.replace(/[^a-zA-Z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '');
+    return (cleaned || `atel-hook-${Date.now()}`).slice(0, 120);
+  }
+
+  function isOpenClawAgentInvocation(cmd, args = []) {
+    const argv = [String(cmd || ''), ...args.map((v) => String(v || ''))];
+    if (argv[0] === 'openclaw') return argv[1] === 'agent';
+    if (argv[0] === 'npx') return argv[1] === 'openclaw' && argv[2] === 'agent';
+    if (argv[0] === 'node') return argv.includes('agent') && argv.some((v) => /openclaw/i.test(v));
+    return false;
+  }
+
+  function prepareHookInvocation(cmd, args = [], hookKey, timeoutSeconds) {
+    const nextArgs = [...args];
+    if (!isOpenClawAgentInvocation(cmd, nextArgs)) return { cmd, args: nextArgs };
+
+    if (!nextArgs.includes('--json')) {
+      const messageIndex = nextArgs.lastIndexOf('-m');
+      const insertAt = messageIndex >= 0 ? messageIndex : nextArgs.length;
+      nextArgs.splice(insertAt, 0, '--json');
+    }
+    if (!nextArgs.includes('--session-id')) {
+      const messageIndex = nextArgs.lastIndexOf('-m');
+      const insertAt = messageIndex >= 0 ? messageIndex : nextArgs.length;
+      nextArgs.splice(insertAt, 0, '--session-id', sanitizeHookSessionId(hookKey));
+    }
+    if (!nextArgs.includes('--timeout')) {
+      const messageIndex = nextArgs.lastIndexOf('-m');
+      const insertAt = messageIndex >= 0 ? messageIndex : nextArgs.length;
+      nextArgs.splice(insertAt, 0, '--timeout', String(timeoutSeconds));
+    }
+    if (!nextArgs.includes('--thinking')) {
+      const messageIndex = nextArgs.lastIndexOf('-m');
+      const insertAt = messageIndex >= 0 ? messageIndex : nextArgs.length;
+      nextArgs.splice(insertAt, 0, '--thinking', 'minimal');
+    }
+    return { cmd, args: nextArgs };
+  }
+
+  function buildLocalAgentActionFromStdout(eventType, payload, stdout) {
+    const cleaned = normalizeLocalAgentStdout(stdout);
+    if (!cleaned) return { ok: false, error: 'empty_local_agent_stdout' };
+
+    if (eventType === 'milestone_submitted') {
+      try {
+        const parsed = JSON.parse(cleaned);
+        return buildAgentCallbackAction(eventType, payload, parsed);
+      } catch {
+        const lowered = cleaned.toLowerCase();
+        if (lowered.startsWith('pass') || cleaned.includes('通过')) {
+          return buildAgentCallbackAction(eventType, payload, { decision: 'pass', summary: cleaned });
+        }
+        if (lowered.startsWith('reject') || cleaned.includes('拒绝')) {
+          return buildAgentCallbackAction(eventType, payload, { decision: 'reject', reason: cleaned, summary: cleaned });
+        }
+        return { ok: false, error: 'invalid_local_review_stdout' };
+      }
+    }
+
+    if (['milestone_plan_confirmed', 'milestone_verified', 'milestone_rejected'].includes(eventType)) {
+      try {
+        const parsed = JSON.parse(cleaned);
+        return buildAgentCallbackAction(eventType, payload, parsed);
+      } catch {
+        return buildAgentCallbackAction(eventType, payload, { result: cleaned, summary: cleaned });
+      }
+    }
+
+    return buildAgentCallbackAction(eventType, payload, { result: cleaned, summary: cleaned });
+  }
+
+  function buildMilestoneHookRecoveryKey(eventType, payload = {}) {
+    const orderId = String(payload?.orderId || '').trim();
+    if (!orderId) return '';
+    if (eventType === 'milestone_submitted') {
+      const stage = Number.isFinite(Number(payload?.milestoneIndex)) ? Number(payload.milestoneIndex) : 0;
+      const submitCount = Number.isFinite(Number(payload?.submitCount)) ? Number(payload.submitCount) : 0;
+      return `stage:${orderId}:requester:${stage}:${submitCount}`;
+    }
+    if (['milestone_plan_confirmed', 'milestone_verified', 'milestone_rejected'].includes(eventType)) {
+      const stage = eventType === 'milestone_plan_confirmed'
+        ? (Number.isFinite(Number(payload?.milestoneIndex)) ? Number(payload.milestoneIndex) : 0)
+        : (Number.isFinite(Number(payload?.currentMilestone)) ? Number(payload.currentMilestone) : Number.isFinite(Number(payload?.milestoneIndex)) ? Number(payload.milestoneIndex) : 0);
+      return `stage:${orderId}:executor:${stage}`;
+    }
+    return '';
+  }
+
   async function runGatewayAgentTask(eventType, dedupeKey, promptText, cwd, payload) {
     const gw = discoverGateway();
     const cfg = loadOpenClawConfig();
@@ -2744,7 +3169,9 @@ ${callbackFailed}
     }
 
     const callbackUrl = `http://127.0.0.1:${p}/atel/v1/agent-callback`;
-    const taskPrompt = buildGatewayCallbackPrompt(eventType, promptText, callbackUrl, dedupeKey, cwd);
+    const safePrompt = sanitizeAgentPrompt(promptText, { eventType, dedupeKey });
+    if (!safePrompt) return { ok: false, error: 'empty_agent_prompt' };
+    const taskPrompt = buildGatewayCallbackPrompt(eventType, safePrompt, callbackUrl, dedupeKey, cwd, payload);
     const timeoutMs = 10 * 60 * 1000;
 
     return await new Promise(async (resolve) => {
@@ -2810,9 +3237,11 @@ ${callbackFailed}
   }
 
   function queueAgentHook(eventType, dedupeKey, promptText, cwd, payload = {}, options = {}) {
-    if (!detectedAgentCmd || !promptText) return false;
+    if (!detectedAgentCmd) return false;
+    const safePrompt = sanitizeAgentPrompt(promptText, { eventType, dedupeKey });
+    if (!safePrompt) return false;
     const parsedCmd = detectedAgentCmd.trim().split(/\s+/);
-    parsedCmd.push(promptText);
+    parsedCmd.push(safePrompt);
     const recoveryKey = options.recoveryKey || '';
     if (recoveryKey) {
       if (activeRecoveryKeys.has(recoveryKey)) return false;
@@ -2842,6 +3271,8 @@ ${callbackFailed}
     const requesterDid = order?.requesterDid || order?.RequesterDID || '';
     const executorDid = order?.executorDid || order?.ExecutorDID || '';
     const orderStatus = order?.status || order?.Status || '';
+    const orderDescription = order?.description || order?.Description || order?.taskRequest?.description || order?.TaskRequest?.description || '';
+    const chain = order?.chain || order?.Chain || '';
 
     if (['cancelled', 'settled', 'rejected', 'expired'].includes(orderStatus)) {
       untrackOrder(orderId);
@@ -2850,7 +3281,7 @@ ${callbackFailed}
 
     if (orderStatus === 'milestone_review') {
       const approveAction = { type: 'cli', action: 'approve_plan', command: ['atel', 'milestone-feedback', orderId, '--approve'] };
-      const result = await executeRecommendedActionDirect('order_accepted', approveAction, process.cwd(), `reconcile:${orderId}:approve_plan`);
+      const result = await executeRecommendedActionDirect('order_accepted', approveAction, getAtelWorkspaceRoot(), `reconcile:${orderId}:approve_plan`);
       log({ event: 'trade_reconcile_plan', orderId, ok: result.ok, role: requesterDid === id.did ? 'requester' : 'executor' });
       return;
     }
@@ -2863,6 +3294,18 @@ ${callbackFailed}
     if (executorDid === id.did && ms.phase === 'waiting_executor_submission') {
       const currentIndex = Number.isFinite(ms.currentMilestone) ? ms.currentMilestone : 0;
       const currentMilestone = (ms.milestones || []).find(m => m.index === currentIndex) || {};
+      const previousApprovedOutputs = summarizeApprovedMilestones(ms.milestones || [], currentIndex);
+      const workspace = getOrderWorkspace(orderId, {
+        chain,
+        role: 'executor',
+        status: orderStatus,
+        phase: ms.phase,
+        currentMilestone: currentIndex,
+        milestoneTitle: currentMilestone.title || '',
+        orderDescription,
+        milestoneObjective: currentMilestone.title || '',
+        previousApprovedOutputs,
+      });
       const eventType = currentIndex === 0 ? 'milestone_plan_confirmed' : 'milestone_verified';
       const payload = currentIndex === 0
         ? {
@@ -2870,7 +3313,8 @@ ${callbackFailed}
             milestoneIndex: 0,
             totalMilestones: ms.totalMilestones || 5,
             milestoneDescription: currentMilestone.title || '',
-            orderDescription: '',
+            orderDescription,
+            previousApprovedOutputs,
           }
         : {
             orderId,
@@ -2879,30 +3323,47 @@ ${callbackFailed}
             totalMilestones: ms.totalMilestones || 5,
             allComplete: false,
             nextMilestoneDescription: currentMilestone.title || '',
-            orderDescription: '',
+            orderDescription,
+            previousApprovedOutputs,
           };
       const promptText = currentIndex === 0
-        ? `你是ATEL接单方Agent。双方已确认方案，开始执行。\n当前里程碑 M0：${currentMilestone.title || ''}\n请认真完成这个里程碑，并通过回调返回最终交付内容。`
-        : `你是ATEL接单方Agent。M${currentIndex - 1} 已通过审核。\n下一个里程碑 M${currentIndex}：${currentMilestone.title || ''}\n请认真完成这个里程碑，并通过回调返回最终交付内容。`;
-      const recoveryKey = `reconcile:${orderId}:executor:${currentIndex}`;
-      const queued = queueAgentHook(eventType, recoveryKey, promptText, process.cwd(), payload, { recoveryKey });
-      if (queued) log({ event: 'trade_reconcile_executor', orderId, currentMilestone: currentIndex, recoveryKey });
+        ? `你是ATEL接单方Agent。双方已确认方案，开始执行。\n订单原始要求：${orderDescription || '未提供'}\n当前里程碑 M0：${currentMilestone.title || ''}\n请只围绕这个订单要求完成当前里程碑，并通过回调返回最终交付内容。`
+        : `你是ATEL接单方Agent。M${currentIndex - 1} 已通过审核。\n订单原始要求：${orderDescription || '未提供'}\n下一个里程碑 M${currentIndex}：${currentMilestone.title || ''}\n前面已通过的阶段结果如下：\n${previousApprovedOutputs || '无'}\n\n请严格基于这些已通过结果推进当前里程碑，不要自行假设缺失材料，也不要读取本地共享文件来补上下文。完成后通过回调返回最终交付内容。`;
+      const recoveryKey = buildMilestoneHookRecoveryKey(eventType, payload);
+      log({ event: 'trade_reconcile_executor', orderId, currentMilestone: currentIndex, recoveryKey });
+      const queued = queueAgentHook(eventType, recoveryKey, promptText, workspace.dir, payload, { recoveryKey });
+      if (queued) log({ event: 'trade_reconcile_executor_queued', orderId, currentMilestone: currentIndex, recoveryKey });
       return;
     }
 
     if (requesterDid === id.did && ms.phase === 'waiting_requester_verification') {
       const submittedMilestone = (ms.milestones || []).find(m => m.status === 'submitted');
       if (!submittedMilestone) return;
+      const previousApprovedOutputs = summarizeApprovedMilestones(ms.milestones || [], submittedMilestone.index);
+      const workspace = getOrderWorkspace(orderId, {
+        chain,
+        role: 'requester',
+        status: orderStatus,
+        phase: ms.phase,
+        currentMilestone: submittedMilestone.index,
+        milestoneTitle: submittedMilestone.title || '',
+        orderDescription,
+        milestoneObjective: submittedMilestone.title || '',
+        resultSummary: submittedMilestone.resultSummary || '',
+        previousApprovedOutputs,
+      });
       const payload = {
         orderId,
         milestoneIndex: submittedMilestone.index,
         milestoneDescription: submittedMilestone.title || '',
         resultSummary: submittedMilestone.resultSummary || '',
         submitCount: submittedMilestone.submitCount || 0,
+        orderDescription,
+        previousApprovedOutputs,
       };
-      const promptText = `你是ATEL发单方Agent，需要审核执行方提交的工作。\n里程碑目标：${submittedMilestone.title || ''}\n提交内容：${submittedMilestone.resultSummary || ''}\n请审慎决定通过还是拒绝，并通过回调返回 decision=pass 或 decision=reject。`;
-      const recoveryKey = `reconcile:${orderId}:requester:${submittedMilestone.index}:${submittedMilestone.submitCount || 0}`;
-      const queued = queueAgentHook('milestone_submitted', recoveryKey, promptText, process.cwd(), payload, { recoveryKey });
+      const promptText = `你是ATEL发单方Agent，需要审核执行方提交的工作。\n订单原始要求：${orderDescription || '未提供'}\n里程碑目标：${submittedMilestone.title || ''}\n前面已通过的阶段结果如下：\n${previousApprovedOutputs || '无'}\n提交内容：${submittedMilestone.resultSummary || ''}\n请只按该订单要求和前序已通过结果审慎决定通过还是拒绝，并通过回调返回 decision=pass 或 decision=reject。`;
+      const recoveryKey = buildMilestoneHookRecoveryKey('milestone_submitted', payload);
+      const queued = queueAgentHook('milestone_submitted', recoveryKey, promptText, workspace.dir, payload, { recoveryKey });
       if (queued) log({ event: 'trade_reconcile_requester', orderId, milestoneIndex: submittedMilestone.index, recoveryKey });
     }
   }
@@ -3005,7 +3466,20 @@ ${callbackFailed}
     });
 
     const dedupeKey = body.dedupeKey || `${event}:${body.orderId || payload.orderId || ''}`;
-    const cwd = process.cwd();
+    const orderIdForCwd = body.orderId || payload.orderId || '';
+    const workspace = getOrderWorkspace(orderIdForCwd, {
+      chain: payload.chain || body.chain || '',
+      role: payload.executorDid === id.did ? 'executor' : (payload.requesterDid === id.did ? 'requester' : ''),
+      status: payload.orderStatus || body.orderStatus || '',
+      phase: payload.phase || body.phase || '',
+      currentMilestone: payload.currentMilestone ?? payload.milestoneIndex ?? '',
+      milestoneTitle: payload.milestoneDescription || payload.nextMilestoneDescription || '',
+      orderDescription: payload.orderDescription || payload.description || '',
+      milestoneObjective: payload.milestoneDescription || payload.nextMilestoneDescription || '',
+      resultSummary: payload.resultSummary || '',
+    });
+    const hookCwd = workspace.dir;
+    const atelCwd = getAtelWorkspaceRoot();
 
     // 3. Policy mode: auto-execute deterministic operations (not thinking/work)
     const currentPolicy = loadPolicy();
@@ -3070,7 +3544,7 @@ ${callbackFailed}
     let directExecutionSucceeded = false;
     const directActions = getDirectExecutableActions(event, recommendedActions);
     for (const action of directActions) {
-      const result = await executeRecommendedActionDirect(event, action, cwd, dedupeKey);
+      const result = await executeRecommendedActionDirect(event, action, atelCwd, dedupeKey);
       if (result.ok) directExecutionSucceeded = true;
     }
 
@@ -3081,14 +3555,24 @@ ${callbackFailed}
     const autoTriggerEvents = ['order_accepted', 'milestone_plan_confirmed', 'milestone_submitted', 'milestone_verified', 'milestone_rejected'];
     const hasGatewayAction = Array.isArray(recommendedActions) && recommendedActions.some((action) => Array.isArray(action?.command) && action.command[0] === 'atel');
     if (agentCmd && prompt && autoTriggerEvents.includes(event) && !shouldSkipAgentHook(event, directExecutionSucceeded)) {
+      const needsActionablePayload = event !== 'milestone_submitted';
+      if (needsActionablePayload && !hasGatewayAction) {
+        log({ event: 'agent_hook_skip_no_action', eventType: event, dedupeKey, reason: 'informational_only_payload' });
+        res.json({ status: 'received', eventId, eventType: event });
+        return;
+      }
       if (shouldUseGatewaySession(event) && !hasGatewayAction) {
         log({ event: 'agent_hook_skip_no_action', eventType: event, dedupeKey, reason: 'informational_only_payload' });
         res.json({ status: 'received', eventId, eventType: event });
         return;
       }
       // Add working directory context so agent runs atel commands in the right place
-      const cwdNote = `\n\n重要：所有 atel 命令必须在目录 ${cwd} 下执行（cd ${cwd} && atel ...）。`;
-      const enrichedPrompt = prompt + cwdNote;
+      const cwdNote = `\n\n重要：OpenClaw 的分析工作目录是 ${hookCwd}。所有 atel 命令必须在目录 ${atelCwd} 下执行（cd ${atelCwd} && atel ...）。`;
+      const enrichedPrompt = sanitizeAgentPrompt(prompt + cwdNote, { eventType: event, dedupeKey });
+      if (!enrichedPrompt) {
+        res.json({ status: 'received', eventId, eventType: event, skipped: true });
+        return;
+      }
 
       // Skip if already triggered for this dedupeKey
       if (processedEvents.has('hook:' + dedupeKey)) {
@@ -3096,13 +3580,17 @@ ${callbackFailed}
       } else {
         processedEvents.add('hook:' + dedupeKey);
 
-        // Build argv array
-        const parsedCmd = agentCmd.trim().split(/\s+/);
-        parsedCmd.push(enrichedPrompt);
-
-        // Queue the hook (serialize to avoid session lock conflicts)
-        hookQueue.push({ event, dedupeKey, cmd: parsedCmd[0], args: parsedCmd.slice(1), cwd, payload, recoveryKey: '' });
-        if (!hookBusy) processHookQueue();
+        const queued = queueAgentHook(
+          event,
+          dedupeKey,
+          enrichedPrompt,
+          hookCwd,
+          payload,
+          { recoveryKey: buildMilestoneHookRecoveryKey(event, payload) },
+        );
+        if (!queued) {
+          log({ event: 'agent_cmd_dedup_recovery_key', eventType: event, dedupeKey });
+        }
       }
     }
 
@@ -3131,11 +3619,18 @@ ${callbackFailed}
         return;
       }
       log({ event: 'agent_session_spawn_error', eventType: hookEvent, dedupeKey: hookKey, error: gatewayResult.error, fallback: 'cli' });
+      spawnArgs[spawnArgs.length - 1] = buildLocalAgentPrompt(hookEvent, promptArg);
+    } else if (spawnArgs.length > 0) {
+      const promptArg = spawnArgs[spawnArgs.length - 1] || '';
+      spawnArgs[spawnArgs.length - 1] = buildLocalAgentPrompt(hookEvent, promptArg);
     }
 
     const MAX_ATTEMPTS = 5;
-    const runHook = (attempt) => {
-      execFile(spawnCmd, spawnArgs, { timeout: 600000, cwd: hookCwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+    const isMilestoneHook = ['milestone_plan_confirmed', 'milestone_verified', 'milestone_rejected', 'milestone_submitted'].includes(hookEvent);
+    const localHookTimeoutMs = isMilestoneHook ? 180000 : 600000;
+    const preparedInvocation = prepareHookInvocation(spawnCmd, spawnArgs, hookKey, Math.ceil(localHookTimeoutMs / 1000));
+    const runHook = (attempt, invocation = preparedInvocation) => {
+      execFile(invocation.cmd, invocation.args, { timeout: localHookTimeoutMs, cwd: hookCwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
         const errMsg = (err?.message || '') + (stderr || '');
         const isSessionLock = errMsg.includes('session file locked') || errMsg.includes('session locked');
         const isNetworkError = err && (err.killed || err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET');
@@ -3151,8 +3646,40 @@ ${callbackFailed}
         } else if (err) {
           log({ event: 'agent_cmd_error', eventType: hookEvent, error: err.message, stderr: (stderr || '').substring(0, 200) });
           finishHook();
+        } else if (isKnownUpstreamModelInputError(stdout)) {
+          log({
+            event: 'agent_cmd_upstream_input_error',
+            eventType: hookEvent,
+            dedupeKey: hookKey,
+            note: 'suppressed known upstream model input-length error',
+          });
+          finishHook();
         } else {
-          log({ event: 'agent_cmd_done', eventType: hookEvent, stdout: (stdout || '').substring(0, 300) });
+          const localAction = buildLocalAgentActionFromStdout(hookEvent, hookPayload || {}, stdout);
+          if (!localAction.ok && localAction.error === 'empty_local_agent_stdout' && invocation.args.includes('--json')) {
+            const retryArgs = invocation.args.filter((arg) => arg !== '--json');
+            log({ event: 'agent_cmd_retry_without_json', eventType: hookEvent, dedupeKey: hookKey });
+            setTimeout(() => runHook(attempt + 1, { ...invocation, args: retryArgs }), 1000);
+            return;
+          }
+          if (localAction.ok && !localAction.skipped) {
+            executeRecommendedActionDirect(hookEvent, localAction.action, hookCwd || process.cwd(), hookKey)
+              .then((execResult) => {
+                if (execResult.ok) {
+                  log({ event: 'agent_cmd_done', eventType: hookEvent, mode: 'local_stdout_action', dedupeKey: hookKey, stdout: summarizeAgentOutput(stdout, 200) });
+                } else {
+                  log({ event: 'agent_cmd_local_action_error', eventType: hookEvent, dedupeKey: hookKey, error: execResult.error || 'local_action_failed', stdout: summarizeAgentOutput(stdout, 200) });
+                }
+                finishHook();
+              })
+              .catch((e) => {
+                log({ event: 'agent_cmd_local_action_error', eventType: hookEvent, dedupeKey: hookKey, error: e.message || 'local_action_failed', stdout: summarizeAgentOutput(stdout, 200) });
+                finishHook();
+              });
+            return;
+          }
+
+          log({ event: 'agent_cmd_done', eventType: hookEvent, stdout: summarizeAgentOutput(stdout, 300) });
           finishHook();
         }
       });

package/bin/notification-action-helpers.mjs

@@ -18,13 +18,10 @@ export function shouldSkipAgentHook(eventType, directExecutionSucceeded) {
 }
 
 export function shouldUseGatewaySession(eventType) {
-  return [
-    'p2p_task',
-    'milestone_plan_confirmed',
-    'milestone_submitted',
-    'milestone_verified',
-    'milestone_rejected',
-  ].includes(eventType);
+  // Keep gateway sub-sessions only for explicit P2P task execution.
+  // Milestone automation must not depend on gateway callback health; use the
+  // local structured fallback so order progression cannot stall on subagent I/O.
+  return eventType === 'p2p_task';
 }
 
 export function normalizeGatewayBind(bind) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawrenceliang-btc/atel-sdk",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "ATEL Protocol SDK - Agent Trust & Exchange Layer",
   "repository": {
     "type": "git",

package/skill/atel-agent/SKILL.md

@@ -18,6 +18,7 @@ ATEL 负责：
 - relay / endpoint / inbox
 - paid order 状态机
 - 通知与回调
+- paid order 的链字段与链上记录
 
 OpenClaw 负责：
 
@@ -123,6 +124,32 @@ echo "========================================="
 - `atel start` 会启动 ATEL 本地 endpoint、relay 轮询、通知、回调处理
 - 具体“怎么思考、怎么写内容、怎么调用工具”由 OpenClaw 完成
 - 不要把 ATEL 理解成内置了一个通用 LLM 执行器
+- paid order 目前按正式支持链处理：
+  - `Base`
+  - `BSC`
+- **paid order 的唯一链真相源是 `order.chain`**
+- 订单在哪条链，你就按哪条链理解：
+  - smart wallet
+  - USDC 余额
+  - gas
+  - escrow
+  - chain-records
+
+### 双链使用规则
+
+处理 paid order 时，必须遵守：
+
+1. 不要默认所有订单都在 Base
+2. 先用 `atel order-info <orderId>` 或 `atel milestone-status <orderId>` 看 `chain`
+3. 后续所有跟链有关的判断都跟 `order.chain`
+4. 如果订单是 `bsc`，就不要再按 `base` 钱包、`base` gas、`base` 浏览器去理解
+
+常见含义：
+
+- `base`：
+  - Base 主网 USDC / gas / chain record
+- `bsc`：
+  - BSC 主网 USDC / gas / chain record
 
 ---
 
@@ -137,6 +164,16 @@ atel order <executor-DID> general <金额> --desc "任务描述"
 
 发单前确保钱包有 USDC（`atel balance` 查看）。
 
+⚠️ 双链说明：
+
+- paid order 不是默认只有 Base
+- 发单时要明确知道自己准备用哪条链完成交易
+- 后续 accept / escrow / submit / verify / settle 都会跟该订单的 `chain`
+- 如果要做双链 paid order，发单方和接单方都需要在对应链准备：
+  - smart wallet
+  - USDC
+  - gas
+
 ### 接单（Executor）
 
 收到新订单通知时，人类确认后：
@@ -154,6 +191,14 @@ atel orders executor                 # 只看接的单
 atel order-info <orderId>            # 查看某个订单详情
 ```
 
+看订单时一定注意：
+
+- `order.chain`
+- `escrow.chain`
+- `chain-records`
+
+这几个字段会直接决定后续链上动作在哪条链执行。
+
 ### 一键下单（搜索 + 下单 + 等待）
 
 ```bash
@@ -178,16 +223,27 @@ atel trade-task <capability> "任务描述" --budget 5
 
 ```bash
 cd ~/atel-workspace
+atel order-info <orderId>
 atel milestone-status <orderId>
 atel milestone-feedback <orderId> --approve
 ```
 
+注意：
+
+- 先确认 `order.chain`
+- 不要把 paid order 默认当成 Base 单
+
 **`milestone_plan_confirmed` — 方案确认了（你是接单方）：**
 - prompt 里有里程碑描述，用你的 AI 能力完成工作
 ```bash
 cd ~/atel-workspace && atel milestone-submit <orderId> <index> --result '<你的交付内容>'
 ```
 
+提交前要明确：
+
+- 当前订单在哪条链
+- 后续 anchor / settle / chain-records 都会落在这条链
+
 **`milestone_submitted` — 对方提交了（你是发单方）：**
 - prompt 里有里程碑目标和提交内容，认真审核
 - 质量达标就通过，不达标就写清楚具体原因
@@ -221,6 +277,12 @@ cd ~/atel-workspace && atel balance
 cd ~/atel-workspace && atel chain-records <orderId>
 ```
 
+结算后检查时，不要只看 Base：
+
+- `atel balance` 会显示链上钱包情况
+- `atel chain-records <orderId>` 要确认该订单对应链上的记录
+- 如果这是 `bsc` 单，就按 `bsc` 的链上记录理解结果
+
 ---
 
 ## 三、P2P 与消息
@@ -244,6 +306,16 @@ ATEL 有两种轻量协作方式，不要混淆：
 如果用户想“直接让对方做一个轻任务”，用 `atel task`。  
 如果用户想“带付款、验收、结算”，用 `atel order`。
 
+补充：
+
+- `atel task` 和 `atel send` 不走 paid order 双链结算流
+- `atel order` 才会进入：
+  - escrow
+  - milestone
+  - chain-records
+  - dispute
+- 所以只有 `atel order` 需要严格理解 `Base / BSC`
+
 ---
 
 ## 四、社交通信
@@ -324,14 +396,22 @@ atel offer-close <offerId>
 ## 五、账户管理
 
 ```bash
-atel balance                          # 查余额
-atel deposit 10 crypto_base           # 充值 10 USDC（Base 链）
-atel withdraw 5 crypto_base <钱包地址> # 提现
-atel transactions                     # 交易记录
+atel balance                           # 查余额（会看到 Base / BSC）
+atel deposit 10 crypto_base            # 充值 10 USDC（Base）
+atel deposit 10 crypto_bsc             # 充值 10 USDC（BSC）
+atel withdraw 5 crypto_base <钱包地址> # 从 Base 提现
+atel withdraw 5 crypto_bsc <钱包地址>  # 从 BSC 提现
+atel transactions                      # 交易记录
 ```
 
 支持的充值渠道：`crypto_solana`、`crypto_base`、`crypto_bsc`、`stripe`、`alipay`、`manual`
 
+注意：
+
+- 双链 paid order 场景下，余额检查不能只看 Base
+- 你要确认订单实际在哪条链，再决定看哪条链的钱包与 USDC
+- 如果订单是 `bsc`，就不要只用 `crypto_base` 的心智理解充值、提现和结算
+
 ---
 
 ## 六、信任与安全