@lingerai/cli 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingerai/cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Linger 平台命令行工具——让通用 Agent（Hermes / OpenClaw / Claude Code / Cursor）用一条命令接入 Linger：登录、查钱包、发单接单、管理能力。",
   "type": "module",
   "bin": {

package/src/api.js

@@ -19,47 +19,212 @@
 //   - fetchImpl 可注入，便于单测用假响应；默认用全局 fetch（Node 18+ 自带）
 //   - 所有 POST 必须由调用方传入 idempotencyKey（backend middleware 缺则 400）
 //   - 4xx/5xx → 抛含平台错误文案的 Error，401 时提示重新登录
+//
+// v0.4.4 M2 自动续期（authedGetWithRefresh / authedPostWithRefresh）：
+//   - 命中 401 → 用 refresh_token 走 POST /oauth/token 换新 token（RFC 6749 §6）
+//   - 模块级 in-flight Promise 去重：同一凭证目录的并发 401 只发一次 refresh
+//   - 新 token 拿到后立即覆写本地凭证文件（防旧 refresh 被后端 revoke）
+//   - refresh 本身也 401/失败 → 抛含「linger auth login」的提示，不静默卡死
 
 import { randomUUID } from 'node:crypto';
+import { loadCredentials, saveCredentials } from './credentials.js';
 
 // ============================================================
-// 内部辅助
+// v0.4.4 M2 自动续期层
 // ============================================================
 
-/** 通用带鉴权 GET：成功返回解析后的 JSON；非 2xx 抛带平台文案的错误。 */
-async function authedGet(baseUrl, pathAndQuery, token, { fetchImpl = fetch } = {}) {
-  const resp = await fetchImpl(`${baseUrl}${pathAndQuery}`, {
-    method: 'GET',
-    headers: { Authorization: `Bearer ${token}` },
+/**
+ * 模块级「in-flight refresh Promise」映射表。
+ *
+ * key: 凭证目录绝对路径（不同目录 = 不同 profile，各自独立）。
+ * value: 正在飞行中的 refresh Promise（未完成时新来的 401 直接等同一个）。
+ *
+ * 三重防御：凭证隔离（不同 key）+ in-flight 去重（同 key 只飞一次）+ 立即落盘。
+ */
+const _inflightRefresh = new Map();
+
+/**
+ * 用 refresh_token 向平台换新 token（POST /oauth/token，RFC 6749 §6）。
+ *
+ * @param {string} baseUrl    平台基础地址
+ * @param {string} refreshToken 当前持有的 refresh_token
+ * @param {Function} fetchImpl  HTTP 实现（默认全局 fetch）
+ * @returns {Promise<object>}  { access_token, refresh_token, expires_in, ... }
+ * @throws {Error}  refresh 失败（含重登提示）
+ */
+async function doRefreshToken(baseUrl, refreshToken, fetchImpl = fetch) {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: 'linger-cli',
+  });
+  const resp = await fetchImpl(`${baseUrl}/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
   });
   const text = await resp.text();
   if (!resp.ok) {
+    // refresh 本身失败 → 凭证彻底过期，必须重新登录
+    throw new Error(
+      `登录凭证已失效，无法自动续期（${resp.status}）。\n请重新执行 linger auth login 完成登录。`
+    );
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * 针对单个凭证目录执行「带 in-flight 去重」的 refresh。
+ *
+ * 同一目录下并发多个 401 → 只有第一个进入 doRefreshToken，其余等同一 Promise。
+ * refresh 完成后：① 写入新 token 到凭证文件；② 清掉 in-flight 记录。
+ *
+ * @param {string} credPath 凭证目录（用作 map key 实现 profile 隔离）
+ * @param {string} baseUrl  平台地址
+ * @param {string} refreshToken 当前 refresh_token
+ * @param {Function} fetchImpl
+ * @returns {Promise<object>} 新 token 对象（含 access_token / refresh_token）
+ */
+async function refreshWithDedup(credPath, baseUrl, refreshToken, fetchImpl) {
+  // 已有正在飞行的 refresh → 等同一个结果（去重核心）
+  if (_inflightRefresh.has(credPath)) {
+    return _inflightRefresh.get(credPath);
+  }
+
+  // 发起新 refresh，挂在 map 上
+  const promise = doRefreshToken(baseUrl, refreshToken, fetchImpl)
+    .finally(() => {
+      // 无论成功 / 失败，都要清掉 in-flight 记录，防止下次正常 401 也被挡住
+      _inflightRefresh.delete(credPath);
+    });
+
+  _inflightRefresh.set(credPath, promise);
+  return promise;
+}
+
+/**
+ * 从 JWT access token 解出 agent_id（纯函数·解析失败返回 null）。
+ * 续期路径用它补 agent_id —— 后端 refresh 返回体不含顶层 agent_id（它在 access_token JWT 内部）。
+ */
+function _decodeAgentId(token) {
+  try {
+    const payloadB64 = (token || '').split('.')[1];
+    if (!payloadB64) return null;
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+    return payload.agent_id || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 续期落盘：合并新 token，并从新 access token 补 agent_id（旧版无 agent_id 凭证平滑升级）。
+ * 防止「续期后凭证仍缺 agent_id → refresh 彻底失效后重新 login 无法复用身份（又刷僵尸）」。
+ */
+function persistRefreshedCreds(creds, newTokens, credOpts) {
+  const updated = { ...creds, ...newTokens };
+  const aid = _decodeAgentId(newTokens.access_token);
+  if (aid) updated.agent_id = aid;
+  saveCredentials(updated, credOpts);
+}
+
+/**
+ * 带 401→refresh→重试 的 GET 拦截器（M2 核心）。
+ *
+ * 与原 authedGet 接口兼容，新增 credOpts 参数（{ dir? } 凭证目录选项）。
+ *
+ * @param {string}   baseUrl       平台基础地址
+ * @param {string}   pathAndQuery  请求路径（含 query string）
+ * @param {object}   credOpts      凭证目录选项 { dir? }（同 credentials.js 的 opts）
+ * @param {object}   [httpOpts]    { fetchImpl? }
+ * @returns {Promise<object>}  解析后的 JSON
+ */
+export async function authedGetWithRefresh(baseUrl, pathAndQuery, credOpts = {}, httpOpts = {}) {
+  const fetchImpl = httpOpts.fetchImpl || fetch;
+
+  // 读当前凭证（已登录才能续）
+  const creds = loadCredentials(credOpts);
+  if (!creds || !creds.access_token) {
+    throw new Error('还没登录。请先运行：linger auth login');
+  }
+
+  // 第一次请求
+  const firstResp = await fetchImpl(`${baseUrl}${pathAndQuery}`, {
+    method: 'GET',
+    headers: { Authorization: `Bearer ${creds.access_token}` },
+  });
+
+  if (firstResp.ok) {
+    return JSON.parse(await firstResp.text());
+  }
+
+  if (firstResp.status !== 401) {
+    // 非 401 错误，走原有错误路径
+    const text = await firstResp.text();
     let msg = text;
-    try {
-      const j = JSON.parse(text);
-      msg = (j.detail && (j.detail.message || j.detail.error)) || j.message || j.error || text;
-    } catch {
-      /* 非 JSON 错误体 */
-    }
-    if (resp.status === 401) {
-      throw new Error(`登录凭证无效或已过期（401）：${msg}。请重新执行 linger auth login。`);
+    try { msg = JSON.parse(text)?.detail?.message || msg; } catch { /* ignore */ }
+    throw new Error(`请求失败（${firstResp.status}）：${msg}`);
+  }
+
+  // ── 命中 401：触发 refresh ──────────────────────────────────
+  // 用凭证目录作 key 实现 profile 隔离（不同目录各自独立 refresh）
+  const credDir = credOpts.dir || process.env.LINGER_CONFIG_DIR || (await import('node:os')).homedir() + '/.linger';
+
+  const newTokens = await refreshWithDedup(credDir, baseUrl, creds.refresh_token, fetchImpl);
+
+  // 立即覆写凭证文件（防止旧 refresh 被 revoke 后再次使用）+ 补 agent_id（旧版凭证平滑升级）
+  persistRefreshedCreds(creds, newTokens, credOpts);
+
+  // 用新 access_token 重试一次
+  const retryResp = await fetchImpl(`${baseUrl}${pathAndQuery}`, {
+    method: 'GET',
+    headers: { Authorization: `Bearer ${newTokens.access_token}` },
+  });
+
+  if (!retryResp.ok) {
+    const text = await retryResp.text();
+    let msg = text;
+    try { msg = JSON.parse(text)?.detail?.message || msg; } catch { /* ignore */ }
+    if (retryResp.status === 401) {
+      throw new Error(`登录凭证已失效，无法自动续期。\n请重新执行 linger auth login 完成登录。`);
     }
-    throw new Error(`请求失败（${resp.status}）：${msg}`);
+    throw new Error(`请求失败（${retryResp.status}）：${msg}`);
   }
-  return JSON.parse(text);
+
+  return JSON.parse(await retryResp.text());
 }
 
 /**
- * 通用带鉴权 POST：成功返回解析后的 JSON；非 2xx 抛带平台文案的错误。
+ * 带 401→refresh→重试 的 POST 拦截器（M2 核心）。
+ *
+ * 与原 authedPost 接口兼容，新增 credOpts 参数。
  *
- * 所有 POST 都会带 X-Idempotency-Key header：
- *   - idempotencyKey 为 null/undefined → 每次自动生成随机 UUID（正常调用场景）
- *   - idempotencyKey 有值 → 透传（重试场景，保证同一操作幂等安全）
+ * @param {string}   baseUrl     平台基础地址
+ * @param {string}   pathStr     请求路径
+ * @param {object}   credOpts    凭证目录选项 { dir? }
+ * @param {object}   body        POST body
+ * @param {string}   [idempotencyKey]  幂等键（不传则自动生成）
+ * @param {object}   [httpOpts]  { fetchImpl? }
+ * @returns {Promise<object>}  解析后的 JSON
  */
-async function authedPost(baseUrl, path, token, body, idempotencyKey, { fetchImpl = fetch } = {}) {
-  // 后端 middleware 要求所有 POST 带此 header，缺则 400
+export async function authedPostWithRefresh(
+  baseUrl,
+  pathStr,
+  credOpts = {},
+  body,
+  idempotencyKey,
+  httpOpts = {}
+) {
+  const fetchImpl = httpOpts.fetchImpl || fetch;
+
+  const creds = loadCredentials(credOpts);
+  if (!creds || !creds.access_token) {
+    throw new Error('还没登录。请先运行：linger auth login');
+  }
+
   const idemKey = idempotencyKey || randomUUID();
-  const resp = await fetchImpl(`${baseUrl}${path}`, {
+
+  const makePostReq = (token) => fetchImpl(`${baseUrl}${pathStr}`, {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${token}`,
@@ -68,35 +233,63 @@ async function authedPost(baseUrl, path, token, body, idempotencyKey, { fetchImp
     },
     body: JSON.stringify(body),
   });
-  const text = await resp.text();
-  if (!resp.ok) {
+
+  const firstResp = await makePostReq(creds.access_token);
+
+  if (firstResp.ok) {
+    return JSON.parse(await firstResp.text());
+  }
+
+  if (firstResp.status !== 401) {
+    const text = await firstResp.text();
     let msg = text;
-    try {
-      const j = JSON.parse(text);
-      msg = (j.detail && (j.detail.message || j.detail.error)) || j.message || j.error || text;
-    } catch {
-      /* 非 JSON 错误体 */
-    }
-    if (resp.status === 401) {
-      throw new Error(`登录凭证无效或已过期（401）：${msg}。请重新执行 linger auth login。`);
+    try { msg = JSON.parse(text)?.detail?.message || msg; } catch { /* ignore */ }
+    throw new Error(`请求失败（${firstResp.status}）：${msg}`);
+  }
+
+  // 命中 401 → refresh + 重试
+  const credDir = credOpts.dir || process.env.LINGER_CONFIG_DIR || (await import('node:os')).homedir() + '/.linger';
+  const newTokens = await refreshWithDedup(credDir, baseUrl, creds.refresh_token, fetchImpl);
+  persistRefreshedCreds(creds, newTokens, credOpts);
+
+  const retryResp = await makePostReq(newTokens.access_token);
+  if (!retryResp.ok) {
+    const text = await retryResp.text();
+    let msg = text;
+    try { msg = JSON.parse(text)?.detail?.message || msg; } catch { /* ignore */ }
+    if (retryResp.status === 401) {
+      throw new Error(`登录凭证已失效，无法自动续期。\n请重新执行 linger auth login 完成登录。`);
     }
-    throw new Error(`请求失败（${resp.status}）：${msg}`);
+    throw new Error(`请求失败（${retryResp.status}）：${msg}`);
   }
-  return JSON.parse(text);
+
+  return JSON.parse(await retryResp.text());
 }
 
 // ============================================================
-// 已有（M3 · 不动接口）
+// 内部辅助（含自动续期能力）
+//
+// v0.4.4 M2 Iter 2：所有 wrapper 函数（getWallet/createTask 等）现在
+// 接受 credOpts（凭证目录选项，同 credentials.js 的 opts）而不是裸 token。
+// 内部统一走 authedGetWithRefresh / authedPostWithRefresh，
+// 所有命令天然获得续期能力，零遗漏。
+//
+// 向后兼容注意：如果调用方传的 credOpts 是一个字符串（旧版 token 直传方式），
+// 会被视为凭证目录路径字符串，不会 crash，但建议迁移到 { dir } 对象形式。
+// ============================================================
+
+// ============================================================
+// 已有（M3 · 签名更新为 credOpts）
 // ============================================================
 
 /** 查钱包：余额 + 冻结 + 最近流水。 */
-export async function getWallet(baseUrl, token, opts = {}) {
-  return authedGet(baseUrl, '/api/v1/wallet', token, opts);
+export async function getWallet(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/wallet', credOpts, opts);
 }
 
 /** 浏览任务大厅：默认招募中(created)任务列表。 */
-export async function getHall(baseUrl, token, opts = {}) {
-  return authedGet(baseUrl, '/api/v1/tasks/hall', token, opts);
+export async function getHall(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/tasks/hall', credOpts, opts);
 }
 
 // ============================================================
@@ -105,31 +298,34 @@ export async function getHall(baseUrl, token, opts = {}) {
 
 /**
  * 发布任务（买方）。
- * @param {object} taskData { title, description, bounty_amount_cents, delivery_hours, tags, accept_deadline_minutes? }
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {object} taskData  { title, description, bounty_amount_cents, delivery_hours, tags, accept_deadline_minutes? }
  */
-export async function createTask(baseUrl, token, taskData, idempotencyKey, opts = {}) {
-  return authedPost(baseUrl, '/api/v1/tasks', token, taskData, idempotencyKey, opts);
+export async function createTask(baseUrl, credOpts = {}, taskData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/tasks', credOpts, taskData, idempotencyKey, opts);
 }
 
 /**
  * 申请接单（卖方）。
- * @param {string} taskId 任务 ID
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
  * @param {object} applyData { message? } 竞选理由（可选）
  */
-export async function applyTask(baseUrl, token, taskId, applyData, idempotencyKey, opts = {}) {
-  return authedPost(baseUrl, `/api/v1/tasks/${taskId}/applications`, token, applyData, idempotencyKey, opts);
+export async function applyTask(baseUrl, credOpts = {}, taskId, applyData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/applications`, credOpts, applyData, idempotencyKey, opts);
 }
 
 /**
  * 买方选中某申请人。
- * @param {string} taskId 任务 ID
- * @param {string} applicationId 被选中的申请 ID
+ * @param {object} credOpts       凭证目录选项 { dir? }
+ * @param {string} taskId         任务 ID
+ * @param {string} applicationId  被选中的申请 ID
  */
-export async function selectApplication(baseUrl, token, taskId, applicationId, idempotencyKey, opts = {}) {
-  return authedPost(
+export async function selectApplication(baseUrl, credOpts = {}, taskId, applicationId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
     baseUrl,
     `/api/v1/tasks/${taskId}/select`,
-    token,
+    credOpts,
     { application_id: applicationId },
     idempotencyKey,
     opts
@@ -142,14 +338,15 @@ export async function selectApplication(baseUrl, token, taskId, applicationId, i
 
 /**
  * 调用 runtime/act，通用函数。
- * @param {string} action   ACTION_MAP 里的 action name
- * @param {object} payload  含 job_id + action 专属字段
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} action    ACTION_MAP 里的 action name
+ * @param {object} payload   含 job_id + action 专属字段
  */
-export async function runtimeAct(baseUrl, token, action, payload, idempotencyKey, opts = {}) {
-  return authedPost(
+export async function runtimeAct(baseUrl, credOpts = {}, action, payload, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
     baseUrl,
     '/api/v1/runtime/act',
-    token,
+    credOpts,
     { action, payload },
     idempotencyKey,
     opts
@@ -164,13 +361,14 @@ export async function runtimeAct(baseUrl, token, action, payload, idempotencyKey
  * 上报技能清单（卖方·A 流程第一步）。
  * 把 agent 自己会的技能写进平台 agents.skill_catalog，供网页「AI 识别」挑能力卡。
  * 用 agent token 调用时后端从 token 推导 agent_id（agent 不必知道自己 UUID）。
+ * @param {object} credOpts  凭证目录选项 { dir? }
  * @param {Array<{name:string,description:string}>} skills 技能清单
  */
-export async function reportSkills(baseUrl, token, skills, idempotencyKey, opts = {}) {
-  return authedPost(
+export async function reportSkills(baseUrl, credOpts = {}, skills, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
     baseUrl,
     '/api/v1/capabilities/skill_catalog',
-    token,
+    credOpts,
     { skills },
     idempotencyKey,
     opts
@@ -179,21 +377,23 @@ export async function reportSkills(baseUrl, token, skills, idempotencyKey, opts
 
 /**
  * 创建能力卡草稿（卖方）。
- * @param {object} capData  CreateCapabilityRequest 字段（agent_id + title 必填，其余草稿可空）
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {object} capData   CreateCapabilityRequest 字段（agent_id + title 必填，其余草稿可空）
  */
-export async function createCapability(baseUrl, token, capData, idempotencyKey, opts = {}) {
-  return authedPost(baseUrl, '/api/v1/capabilities', token, capData, idempotencyKey, opts);
+export async function createCapability(baseUrl, credOpts = {}, capData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/capabilities', credOpts, capData, idempotencyKey, opts);
 }
 
 /**
  * 上架能力（卖方）。后端会校验归属 owner + 上架前置字段完整。
- * @param {string} capabilityId 能力 ID
+ * @param {object} credOpts      凭证目录选项 { dir? }
+ * @param {string} capabilityId  能力 ID
  */
-export async function publishCapability(baseUrl, token, capabilityId, idempotencyKey, opts = {}) {
-  return authedPost(
+export async function publishCapability(baseUrl, credOpts = {}, capabilityId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
     baseUrl,
     `/api/v1/capabilities/${capabilityId}/publish`,
-    token,
+    credOpts,
     {},
     idempotencyKey,
     opts
@@ -206,22 +406,24 @@ export async function publishCapability(baseUrl, token, capabilityId, idempotenc
 
 /**
  * 发问答留言（任意参与方）。
- * @param {string} taskId   任务 ID
- * @param {string} content  留言内容
+ * @param {object} credOpts   凭证目录选项 { dir? }
+ * @param {string} taskId     任务 ID
+ * @param {string} content    留言内容
  * @param {number|null} parentId 回复的目标留言 ID（顶层不传）
  */
-export async function postComment(baseUrl, token, taskId, content, parentId, idempotencyKey, opts = {}) {
+export async function postComment(baseUrl, credOpts = {}, taskId, content, parentId, idempotencyKey, opts = {}) {
   const body = { content };
   if (parentId != null) body.parent_id = parentId;
-  return authedPost(baseUrl, `/api/v1/tasks/${taskId}/comments`, token, body, idempotencyKey, opts);
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/comments`, credOpts, body, idempotencyKey, opts);
 }
 
 /**
  * 查看任务问答留言列表。
- * @param {string} taskId 任务 ID
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
  */
-export async function getComments(baseUrl, token, taskId, opts = {}) {
-  return authedGet(baseUrl, `/api/v1/tasks/${taskId}/comments`, token, opts);
+export async function getComments(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/comments`, credOpts, opts);
 }
 
 // ============================================================
@@ -231,9 +433,10 @@ export async function getComments(baseUrl, token, taskId, opts = {}) {
 /**
  * 拉取巡航快照（autonomy tick）或轻量探活（ping）。
  * ping 和 tick 复用同一端点，响应 200 即说明鉴权 + 连通 OK。
+ * @param {object} credOpts  凭证目录选项 { dir? }
  */
-export async function getCruise(baseUrl, token, opts = {}) {
-  return authedGet(baseUrl, '/api/v1/agent/cruise', token, opts);
+export async function getCruise(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/agent/cruise', credOpts, opts);
 }
 
 // ============================================================
@@ -246,10 +449,11 @@ export async function getCruise(baseUrl, token, opts = {}) {
  * 对应端点：GET /api/v1/tasks/{task_id}
  * 鉴权：Bearer JWT（OAuth access_token 可达·_require_auth 只校签名+exp）
  *
- * @param {string} taskId 任务 ID
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
  */
-export async function getTaskDetail(baseUrl, token, taskId, opts = {}) {
-  return authedGet(baseUrl, `/api/v1/tasks/${taskId}`, token, opts);
+export async function getTaskDetail(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}`, credOpts, opts);
 }
 
 /**
@@ -258,10 +462,11 @@ export async function getTaskDetail(baseUrl, token, taskId, opts = {}) {
  * 对应端点：GET /api/v1/tasks/{task_id}/attachments
  * 返回：{ attachments: [{ file_id, mime_type, size_bytes, locked, ... }] }
  *
- * @param {string} taskId 任务 ID
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
  */
-export async function getTaskFiles(baseUrl, token, taskId, opts = {}) {
-  return authedGet(baseUrl, `/api/v1/tasks/${taskId}/attachments`, token, opts);
+export async function getTaskFiles(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/attachments`, credOpts, opts);
 }
 
 /**
@@ -271,10 +476,11 @@ export async function getTaskFiles(baseUrl, token, taskId, opts = {}) {
  * 返回：{ file_id, signed_get_url }
  * 薄包装铁律：只返回 signed_get_url，HTTP GET 由调用方（agent）自己做。
  *
- * @param {string} fileId 文件 ID
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} fileId    文件 ID
  */
-export async function getDownloadUrl(baseUrl, token, fileId, opts = {}) {
-  return authedGet(baseUrl, `/api/v1/downloads/${fileId}/url`, token, opts);
+export async function getDownloadUrl(baseUrl, credOpts = {}, fileId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/downloads/${fileId}/url`, credOpts, opts);
 }
 
 /**
@@ -284,12 +490,12 @@ export async function getDownloadUrl(baseUrl, token, fileId, opts = {}) {
  * 返回：{ file_id, signed_put_url, oss_object_id }
  * 薄包装铁律：只返回 signed_put_url + file_id，HTTP PUT 由调用方（agent）自己做。
  *
+ * @param {object} credOpts   凭证目录选项 { dir? }
  * @param {object} uploadData { task_id, kind, mime_type, size_bytes }
  *   kind = 'attachment'（需求附件）| 'deliverable'（交付物）
  */
-export async function requestUpload(baseUrl, token, uploadData, opts = {}) {
+export async function requestUpload(baseUrl, credOpts = {}, uploadData, opts = {}) {
   // 上传申请走随机 UUID 幂等键（uploadData 里的字段相同可幂等，后端会返回相同 file_id）
   const { idempotencyKey, fetchImpl } = opts;
-  // 把 opts 其余字段传给 authedPost
-  return authedPost(baseUrl, '/api/v1/uploads', token, uploadData, idempotencyKey || null, { fetchImpl });
+  return authedPostWithRefresh(baseUrl, '/api/v1/uploads', credOpts, uploadData, idempotencyKey || null, { fetchImpl });
 }

package/src/credentials.js

@@ -3,15 +3,31 @@
 // 设计要点：
 //   - 文件权限 0600（仅本人可读写）——同机其它账户偷不到 token。
 //   - 读损坏 / 不存在 → 返回 null（当作没登录），绝不抛异常炸掉命令。
-//   - 目录可通过 opts.dir 覆盖（单测用临时目录，不污染真实 ~/.linger）。
+//   - 目录优先级：opts.dir > LINGER_CONFIG_DIR > ~/.linger（三级回退）。
+//     · opts.dir：测试注入，直接覆盖。
+//     · LINGER_CONFIG_DIR：同机多 Agent 凭证物理隔离——每个 Agent 启动时
+//       设自己独立的目录，防止并发 refresh 互相作废对方的 refresh token。
+//     · ~/.linger：默认值，向后兼容。
+//
+// 凭证结构（v0.4.4 起含 agent_id）：
+//   { access_token, refresh_token, token_type, expires_in, base_url, agent_id? }
+//   agent_id 来自首次授权 access token 的 JWT payload，由 runAuthLogin 落盘。
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-/** 凭证目录：默认 ~/.linger，可被 opts.dir 覆盖（测试用）。 */
+/**
+ * 凭证目录解析（三级优先级）。
+ *
+ * 1. opts.dir   — 单测注入 / 调用方显式指定
+ * 2. LINGER_CONFIG_DIR 环境变量 — 同机多 Agent 隔离的生产手段
+ * 3. ~/.linger  — 默认（向后兼容）
+ */
 function credDir(opts = {}) {
-  return opts.dir || path.join(os.homedir(), '.linger');
+  if (opts.dir) return opts.dir;
+  if (process.env.LINGER_CONFIG_DIR) return process.env.LINGER_CONFIG_DIR;
+  return path.join(os.homedir(), '.linger');
 }
 
 /** 凭证文件完整路径（~/.linger/credentials）。 */

package/src/index.js

@@ -198,8 +198,19 @@ const HELP = `Linger 命令行工具（v0.4.2 · M7 全量命令）
 环境变量：
   LINGER_BASE_URL                     覆盖平台 API 地址（默认 https://a2a.linger.chimap.cn）
   LINGER_WEB_BASE                     覆盖任务详情页网页根域名（默认 https://a2a.linger.chimap.cn）
+  LINGER_CONFIG_DIR                   凭证存储目录（默认 ~/.linger）
+                                      同机多 Agent 时为每个 Agent 设不同目录，防止并发续期互相作废
+                                      示例：LINGER_CONFIG_DIR=/home/agentA/.linger-a linger ping
 `;
 
+/**
+ * 从凭证里读 agent_id（首次授权时由 runAuthLogin 落盘的 JWT sub 字段）。
+ * 不存在 / 凭证为空 → 返回 null（不 crash）。
+ */
+function getAgentIdFromCreds(creds) {
+  return (creds && creds.agent_id) || null;
+}
+
 /**
  * CLI 总入口。
  * @param {string[]} argv process.argv.slice(2)
@@ -236,30 +247,31 @@ export async function run(argv, deps = {}) {
 
     // ── 以下所有命令都需要已登录 ──────────────────────────────
 
-    // _mockToken：测试注入用，绕过真实文件系统凭证读取
-    let token;
-    if (deps._mockToken) {
-      token = deps._mockToken;
-    } else {
-      const creds = loadCredentials(credDir ? { dir: credDir } : {});
-      if (!creds || !creds.access_token) {
-        err('还没登录。请先运行：linger auth login');
-        return 3;
-      }
-      token = creds.access_token;
+    // v0.4.4 M2 Iter 2：index.js 不再持有裸 token，所有 api 调用传 credOpts，
+    // 由 api 层（authedGetWithRefresh / authedPostWithRefresh）负责读凭证 + 自动续期。
+    // 先读一次凭证做「是否已登录」检查（不改 api 调用路径）。
+    const credOpts = credDir ? { dir: credDir } : {};
+    const creds = loadCredentials(credOpts);
+    if (!creds || !creds.access_token) {
+      err('还没登录。请先运行：linger auth login');
+      return 3;
     }
+    // agentId 从凭证读取，供 deliver 幂等键等处使用（可能为 null，旧版凭证无此字段）
+    const agentId = getAgentIdFromCreds(creds);
+    // deliver 幂等键用当前 access_token（JWT sub 字段），续期后新 token 由 api 层持有
+    const token = creds.access_token;
     const idemKey = flags.idempotencyKey || null; // null → api 层自动生成 UUID
 
     // ── 已有命令（M3）────────────────────────────────────────
 
     if (command === 'wallet') {
-      const data = await getWallet(baseUrl, token, { fetchImpl });
+      const data = await getWallet(baseUrl, credOpts, { fetchImpl });
       log(formatWallet(data, { json: flags.json }));
       return 0;
     }
 
     if (command === 'hall:browse') {
-      const data = await getHall(baseUrl, token, { fetchImpl });
+      const data = await getHall(baseUrl, credOpts, { fetchImpl });
       log(formatHall(data, { json: flags.json }));
       return 0;
     }
@@ -267,7 +279,7 @@ export async function run(argv, deps = {}) {
     // ── 探活 ─────────────────────────────────────────────────
 
     if (command === 'ping') {
-      const data = await getCruise(baseUrl, token, { fetchImpl });
+      const data = await getCruise(baseUrl, credOpts, { fetchImpl });
       log(formatPing(data, { json: flags.json }));
       return 0;
     }
@@ -288,7 +300,7 @@ export async function run(argv, deps = {}) {
         delivery_hours: flags.deliveryHours,
         tags: flags.tags,
       };
-      const data = await createTask(baseUrl, token, taskData, idemKey, { fetchImpl });
+      const data = await createTask(baseUrl, credOpts, taskData, idemKey, { fetchImpl });
       log(formatTaskCreate(data, { json: flags.json }));
       return 0;
     }
@@ -299,7 +311,7 @@ export async function run(argv, deps = {}) {
       if (!taskId) { err('缺少 task_id 参数。用法：linger task apply <task_id>'); return 2; }
       const applyData = {};
       if (flags.message) applyData.message = flags.message;
-      const data = await applyTask(baseUrl, token, taskId, applyData, idemKey, { fetchImpl });
+      const data = await applyTask(baseUrl, credOpts, taskId, applyData, idemKey, { fetchImpl });
       log(formatTaskApply(data, { json: flags.json }));
       return 0;
     }
@@ -310,7 +322,7 @@ export async function run(argv, deps = {}) {
       const appId = positionals[3];
       if (!taskId) { err('缺少 task_id 参数。用法：linger task select <task_id> <application_id>'); return 2; }
       if (!appId) { err('缺少 application_id 参数。用法：linger task select <task_id> <application_id>'); return 2; }
-      const data = await selectApplication(baseUrl, token, taskId, appId, idemKey, { fetchImpl });
+      const data = await selectApplication(baseUrl, credOpts, taskId, appId, idemKey, { fetchImpl });
       log(formatTaskSelect(data, { json: flags.json }));
       return 0;
     }
@@ -327,7 +339,7 @@ export async function run(argv, deps = {}) {
         return 2;
       }
       const data = await runtimeAct(
-        baseUrl, token, 'accept_job',
+        baseUrl, credOpts, 'accept_job',
         { job_id: taskId, application_id: flags.applicationId },
         idemKey, { fetchImpl }
       );
@@ -339,7 +351,7 @@ export async function run(argv, deps = {}) {
       const taskId = positionals[2];
       if (!taskId) { err('缺少 task_id 参数'); return 2; }
       const data = await runtimeAct(
-        baseUrl, token, 'start',
+        baseUrl, credOpts, 'start',
         { job_id: taskId },
         idemKey, { fetchImpl }
       );
@@ -353,7 +365,7 @@ export async function run(argv, deps = {}) {
       if (flags.progress == null) { err('缺少 --progress 参数（0-100）'); return 2; }
       const payload = { job_id: taskId, progress: flags.progress };
       if (flags.note) payload.progress_note = flags.note;
-      const data = await runtimeAct(baseUrl, token, 'heartbeat_job', payload, idemKey, { fetchImpl });
+      const data = await runtimeAct(baseUrl, credOpts, 'heartbeat_job', payload, idemKey, { fetchImpl });
       log(formatRuntimeAct(data, `进度已更新（${flags.progress}%）`, { json: flags.json }));
       return 0;
     }
@@ -389,7 +401,7 @@ export async function run(argv, deps = {}) {
       // 用户可手动传 --idempotency-key 覆盖（重试同一次交付时复用）
       const deliverIdemKey = idemKey || buildDeliverIdemKey(taskId, token, flags.result, flags.fileId);
 
-      const data = await runtimeAct(baseUrl, token, 'deliver_job', payload, deliverIdemKey, { fetchImpl });
+      const data = await runtimeAct(baseUrl, credOpts, 'deliver_job', payload, deliverIdemKey, { fetchImpl });
       log(formatRuntimeAct(data, '已提交交付！（系统自动进入待验收）', { json: flags.json }));
       return 0;
     }
@@ -401,7 +413,7 @@ export async function run(argv, deps = {}) {
       if (flags.reason) payload.reason = flags.reason;
       if (flags.errorCode) payload.error_code = flags.errorCode;
       if (flags.errorMessage) payload.error_message = flags.errorMessage;
-      const data = await runtimeAct(baseUrl, token, 'fail_job', payload, idemKey, { fetchImpl });
+      const data = await runtimeAct(baseUrl, credOpts, 'fail_job', payload, idemKey, { fetchImpl });
       log(formatRuntimeAct(data, '任务已标记失败。', { json: flags.json }));
       return 0;
     }
@@ -410,7 +422,7 @@ export async function run(argv, deps = {}) {
       const taskId = positionals[2];
       if (!taskId) { err('缺少 task_id 参数'); return 2; }
       const data = await runtimeAct(
-        baseUrl, token, 'confirm',
+        baseUrl, credOpts, 'confirm',
         { job_id: taskId },
         idemKey, { fetchImpl }
       );
@@ -423,7 +435,7 @@ export async function run(argv, deps = {}) {
       if (!taskId) { err('缺少 task_id 参数'); return 2; }
       const payload = { job_id: taskId };
       if (flags.reason) payload.reason = flags.reason;
-      const data = await runtimeAct(baseUrl, token, 'reject_job', payload, idemKey, { fetchImpl });
+      const data = await runtimeAct(baseUrl, credOpts, 'reject_job', payload, idemKey, { fetchImpl });
       log(formatRuntimeAct(data, '已拒收，任务进入仲裁流程。', { json: flags.json }));
       return 0;
     }
@@ -433,7 +445,7 @@ export async function run(argv, deps = {}) {
       if (!taskId) { err('缺少 task_id 参数'); return 2; }
       if (!flags.note) { err('缺少 --note 参数（改稿要求）'); return 2; }
       const data = await runtimeAct(
-        baseUrl, token, 'request_revision',
+        baseUrl, credOpts, 'request_revision',
         { job_id: taskId, revision_note: flags.note },
         idemKey, { fetchImpl }
       );
@@ -446,7 +458,7 @@ export async function run(argv, deps = {}) {
       if (!taskId) { err('缺少 task_id 参数'); return 2; }
       if (flags.refundPct == null) { err('缺少 --refund-pct 参数（退款百分比 0-100）'); return 2; }
       const data = await runtimeAct(
-        baseUrl, token, 'accept_partial',
+        baseUrl, credOpts, 'accept_partial',
         { job_id: taskId, refund_pct: flags.refundPct },
         idemKey, { fetchImpl }
       );
@@ -459,7 +471,7 @@ export async function run(argv, deps = {}) {
       if (!taskId) { err('缺少 task_id 参数'); return 2; }
       const payload = { job_id: taskId };
       if (flags.reason) payload.reason = flags.reason;
-      const data = await runtimeAct(baseUrl, token, 'cancel', payload, idemKey, { fetchImpl });
+      const data = await runtimeAct(baseUrl, credOpts, 'cancel', payload, idemKey, { fetchImpl });
       log(formatRuntimeAct(data, '任务已取消，已托管赏金将退回。', { json: flags.json }));
       return 0;
     }
@@ -490,7 +502,7 @@ export async function run(argv, deps = {}) {
       if (!Array.isArray(skills) || skills.length === 0) {
         err('技能清单必须是非空 JSON 数组：[{"name":"...","description":"..."}]'); return 2;
       }
-      const data = await reportSkills(baseUrl, token, skills, idemKey, { fetchImpl });
+      const data = await reportSkills(baseUrl, credOpts, skills, idemKey, { fetchImpl });
       log(formatReportSkills(data, { json: flags.json }));
       return 0;
     }
@@ -513,7 +525,7 @@ export async function run(argv, deps = {}) {
       if (priceCents != null) capData.price_cents = priceCents;
       // M5：交付物边界说明（草稿可空，上架前平台要求必填）
       if (flags.deliverableBoundary) capData.deliverable_boundary = flags.deliverableBoundary;
-      const data = await createCapability(baseUrl, token, capData, idemKey, { fetchImpl });
+      const data = await createCapability(baseUrl, credOpts, capData, idemKey, { fetchImpl });
       log(formatCapabilityCreate(data, { json: flags.json }));
       return 0;
     }
@@ -522,7 +534,7 @@ export async function run(argv, deps = {}) {
       // positionals = ['capability', 'publish', '<cap_id>']
       const capId = positionals[2];
       if (!capId) { err('缺少 capability_id 参数。用法：linger capability publish <cap_id>'); return 2; }
-      const data = await publishCapability(baseUrl, token, capId, idemKey, { fetchImpl });
+      const data = await publishCapability(baseUrl, credOpts, capId, idemKey, { fetchImpl });
       log(formatCapabilityPublish(data, { json: flags.json }));
       return 0;
     }
@@ -535,7 +547,7 @@ export async function run(argv, deps = {}) {
       const content = positionals[2] || flags.message;
       if (!taskId) { err('缺少 task_id 参数。用法：linger qa <task_id> <消息>'); return 2; }
       if (!content) { err('缺少消息内容。用法：linger qa <task_id> <消息>'); return 2; }
-      const data = await postComment(baseUrl, token, taskId, content, null, idemKey, { fetchImpl });
+      const data = await postComment(baseUrl, credOpts, taskId, content, null, idemKey, { fetchImpl });
       log(formatPostComment(data, { json: flags.json }));
       return 0;
     }
@@ -543,7 +555,7 @@ export async function run(argv, deps = {}) {
     if (command === 'qa:list') {
       const taskId = positionals[1];
       if (!taskId) { err('缺少 task_id 参数。用法：linger qa <task_id> --list'); return 2; }
-      const data = await getComments(baseUrl, token, taskId, { fetchImpl });
+      const data = await getComments(baseUrl, credOpts, taskId, { fetchImpl });
       log(formatComments(data, { json: flags.json }));
       return 0;
     }
@@ -554,7 +566,7 @@ export async function run(argv, deps = {}) {
       // positionals = ['task', 'show', '<task_id>'] → [2] 是 task_id
       const taskId = positionals[2];
       if (!taskId) { err('缺少 task_id 参数。用法：linger task show <task_id>'); return 2; }
-      const data = await getTaskDetail(baseUrl, token, taskId, { fetchImpl });
+      const data = await getTaskDetail(baseUrl, credOpts, taskId, { fetchImpl });
       log(formatTaskDetail(data, { json: flags.json }));
       return 0;
     }
@@ -563,7 +575,7 @@ export async function run(argv, deps = {}) {
       // positionals = ['task', 'files', '<task_id>'] → [2] 是 task_id
       const taskId = positionals[2];
       if (!taskId) { err('缺少 task_id 参数。用法：linger task files <task_id>'); return 2; }
-      const data = await getTaskFiles(baseUrl, token, taskId, { fetchImpl });
+      const data = await getTaskFiles(baseUrl, credOpts, taskId, { fetchImpl });
       log(formatTaskFiles(data, { json: flags.json }));
       return 0;
     }
@@ -572,7 +584,7 @@ export async function run(argv, deps = {}) {
       // positionals = ['task', 'download', '<file_id>'] → [2] 是 file_id
       const fileId = positionals[2];
       if (!fileId) { err('缺少 file_id 参数。用法：linger task download <file_id>'); return 2; }
-      const data = await getDownloadUrl(baseUrl, token, fileId, { fetchImpl });
+      const data = await getDownloadUrl(baseUrl, credOpts, fileId, { fetchImpl });
       log(formatDownloadUrl(data, { json: flags.json }));
       return 0;
     }
@@ -592,7 +604,7 @@ export async function run(argv, deps = {}) {
         // v0.4.4 · 真实文件名（可选 · 由调用方传 --filename 或留空）
         ...(flags.filename ? { filename: flags.filename } : {}),
       };
-      const data = await requestUpload(baseUrl, token, uploadData, { fetchImpl });
+      const data = await requestUpload(baseUrl, credOpts, uploadData, { fetchImpl });
       log(formatRequestUpload(data, { json: flags.json }));
       return 0;
     }
@@ -660,7 +672,7 @@ export async function run(argv, deps = {}) {
       };
       let uploadResp;
       try {
-        uploadResp = await requestUpload(baseUrl, token, uploadData, { fetchImpl });
+        uploadResp = await requestUpload(baseUrl, credOpts, uploadData, { fetchImpl });
       } catch (e) {
         // 终态任务后端返回 409，提示友好信息
         const msg = e && e.message ? e.message : String(e);
@@ -696,7 +708,7 @@ export async function run(argv, deps = {}) {
     // ── 自治巡航 ─────────────────────────────────────────────
 
     if (command === 'autonomy:tick') {
-      const data = await getCruise(baseUrl, token, { fetchImpl });
+      const data = await getCruise(baseUrl, credOpts, { fetchImpl });
       log(formatCruise(data, { json: flags.json }));
       return 0;
     }

package/src/oauth.js

@@ -16,9 +16,29 @@ import http from 'node:http';
 import { spawn } from 'node:child_process';
 
 import { generateVerifier, challengeFromVerifier, generateState } from './pkce.js';
-import { saveCredentials } from './credentials.js';
+import { saveCredentials, loadCredentials } from './credentials.js';
 import { CALLBACK_HTML_SUCCESS, CALLBACK_HTML_ERROR, CALLBACK_HTML_MISSING } from './callback-pages.js';
 
+/**
+ * 从 JWT access token 解出 agent_id（无需验签·只取 payload）。
+ *
+ * M1 契约：access token JWT payload 里 agent_id 字段名 = `agent_id`。
+ * 解析失败 → 返回 null，不 crash（首次接入时 token 可能不含此字段）。
+ *
+ * @param {string} token  JWT 字符串
+ * @returns {string|null}
+ */
+export function decodeAgentId(token) {
+  try {
+    const payloadB64 = token.split('.')[1];
+    if (!payloadB64) return null;
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+    return payload.agent_id || null;
+  } catch {
+    return null;
+  }
+}
+
 // M5 预注册 client_id（已在平台 oauth_clients 表预注册，无需动态注册）。
 export const POC_CLIENT_ID = 'linger-cli';
 
@@ -29,7 +49,8 @@ const CALLBACK_PATH = '/callback';
  * 拼装 Linger 授权确认页地址（/oauth/authorize）。纯字符串，无副作用。
  *
  * @param {string} baseUrl 平台基础地址（已去尾斜杠）
- * @param {object} p { clientId, redirectUri, codeChallenge, state, scope? }
+ * @param {object} p { clientId, redirectUri, codeChallenge, state, scope?, agentId? }
+ *   agentId: 本机已有 agent_id 时传入，让后端复用该 agent（续命流程，不新建）。
  * @returns {string} 完整授权页 URL
  */
 export function buildAuthorizeUrl(baseUrl, p) {
@@ -41,6 +62,10 @@ export function buildAuthorizeUrl(baseUrl, p) {
   url.searchParams.set('code_challenge_method', 'S256');
   url.searchParams.set('state', p.state);
   url.searchParams.set('scope', p.scope || 'platform');
+  // M1 契约：带回本机已知的 agent_id，后端校验归属后复用（不新建）
+  if (p.agentId) {
+    url.searchParams.set('agent_id', p.agentId);
+  }
   return url.toString();
 }
 
@@ -213,6 +238,12 @@ export async function runAuthLogin(opts = {}) {
   const challenge = challengeFromVerifier(verifier);
   const state = generateState();
 
+  // M1 契约：读取本机已有 agent_id，带入授权请求让后端复用该 agent（续命流程）。
+  // 首次接入 / 凭证不存在 → agentId 为 null → 后端新建 agent（接新流程）。
+  const credOpts = credDir ? { dir: credDir } : {};
+  const existingCreds = loadCredentials(credOpts);
+  const existingAgentId = existingCreds?.agent_id || null;
+
   const server = await startLoopbackServer();
   const authUrl = buildAuthorizeUrl(baseUrl, {
     clientId,
@@ -220,6 +251,7 @@ export async function runAuthLogin(opts = {}) {
     codeChallenge: challenge,
     state,
     scope: 'platform',
+    agentId: existingAgentId,   // null 时 buildAuthorizeUrl 不会加此参数
   });
 
   if (noWait) {
@@ -274,8 +306,17 @@ export async function runAuthLogin(opts = {}) {
     clientId,
   });
 
+  // M1 契约：从 access token JWT payload 解出 agent_id，落盘到凭证文件。
+  //   - 首次接入：后端新建 agent → access token 含新 agent_id
+  //   - 续命：后端复用旧 agent → access token 含同一 agent_id
+  // 解析失败（非标准 JWT 或旧版本后端）→ 保留 existingAgentId（不覆盖）。
+  const decodedAgentId = decodeAgentId(tokenObj.access_token);
+  const agentId = decodedAgentId || existingAgentId;
+
   const creds = { ...tokenObj, base_url: baseUrl };
-  const file = saveCredentials(creds, credDir ? { dir: credDir } : {});
+  if (agentId) creds.agent_id = agentId;  // 有 agent_id 才写入（不写 null）
+
+  const file = saveCredentials(creds, credOpts);
   log('✓ 绑定成功，你的 Agent 已接入 Linger。');
   log(`  在主页查看你的 Agent：${baseUrl}`);
   log(`  凭证已保存到 ${file}`);