@youzan-cloud/zan-saas-cli 0.1.0-beta.3 → 0.1.0-beta.7

package/src/auth/session.js

@@ -8,6 +8,8 @@ const { openBrowser } = require('./browser');
 const { OAuthError, exchangeCode, refreshTokens, revokeToken } = require('./oauth-client');
 const store = require('./credential-store');
 const { deleteContext } = require('../identity/context-store');
+const { randomUUID } = require('node:crypto');
+const { authSource, credentialChoice } = require('./credential-source');
 
 const dayMs = 24 * 60 * 60 * 1000;
 
@@ -29,7 +31,8 @@ function summary(server, credential, now = Date.now()) {
   if (!credential) return { loggedIn: false, server };
   const iso = value => (Number.isFinite(value) ? new Date(value).toISOString() : null);
   return {
-    loggedIn: Number.isFinite(credential.refreshExpiresAt) ? credential.refreshExpiresAt > now : true,
+    loggedIn: !credential.reauthRequired &&
+      (Number.isFinite(credential.refreshExpiresAt) ? credential.refreshExpiresAt > now : true),
     server,
     clientId: credential.clientId,
     tool: credential.tool,
@@ -43,6 +46,7 @@ async function login({
   env = process.env, browser = true, port = defaultPort, log = message => process.stderr.write(`${message}\n`),
   open = openBrowser, timeoutMs
 } = {}) {
+  authSource(env);
   const config = oauthConfig(env);
   const pkce = createPkce();
   const tool = detectTool(env);
@@ -72,38 +76,66 @@ async function login({
     throw error;
   }
   const credential = {
-    ...tokens, clientId: config.clientId, oauthBaseUrl: config.oauthBaseUrl, tool, loginAt: Date.now()
+    ...tokens, clientId: config.clientId, oauthBaseUrl: config.oauthBaseUrl, tool, loginAt: Date.now(),
+    generation: randomUUID()
   };
-  store.saveCredential(config.server, credential, env);
-  return summary(config.server, credential);
+  await store.withFileLock(env, async () => store.saveCredential(config.server, credential, env));
+  require('../identity/session-store').resetIdentity(env, {
+    pendingCredentialRef: credentialChoice({ ...env, ZAN_SAAS_AUTH_SOURCE: 'personal' }, credential).credentialRef
+  });
+  return status({ env });
 }
 
 async function logout({ env = process.env } = {}) {
   const config = oauthConfig(env);
   const credential = store.readCredential(config.server, env);
-  // The selected shop belongs to this login, so it goes with it.
-  deleteContext(env);
-  if (!credential) return { loggedOut: true, revoked: false, server: config.server };
-  let remoteRevocation = 'revoked';
+  let localContext = 'deleted';
+  for (const clear of [
+    () => deleteContext(env),
+    () => require('../identity/session-store').resetIdentity(env, { logout: true })
+  ]) {
+    try { clear(); } catch { localContext = 'delete_failed'; }
+  }
+  if (!credential && localContext === 'deleted') return { loggedOut: true, revoked: false, server: config.server };
+  let remoteRevocation = credential ? 'revoked' : 'not_attempted';
   let httpStatus;
-  try {
-    await revokeToken(config, credential.refreshToken);
-  } catch (error) {
-    httpStatus = error instanceof OAuthError ? error.httpStatus : undefined;
-    remoteRevocation = httpStatus === undefined ? 'unknown' : 'failed';
+  if (credential) {
+    try {
+      await revokeToken(config, credential.refreshToken);
+    } catch (error) {
+      httpStatus = error instanceof OAuthError ? error.httpStatus : undefined;
+      remoteRevocation = httpStatus === undefined ? 'unknown' : 'failed';
+    }
   }
   let localCredential = 'deleted';
+  let loginChanged = false;
   try {
-    store.deleteCredential(config.server, env);
+    await store.withFileLock(env, async () => {
+      const current = store.readCredential(config.server, env);
+      const sameLogin = !current || (credential?.generation
+        ? current.generation === credential.generation
+        : current.loginAt === credential?.loginAt && current.refreshToken === credential?.refreshToken);
+      if (!sameLogin) {
+        loginChanged = true;
+        throw new Error('The current login changed during logout');
+      }
+      store.deleteCredential(config.server, env);
+    });
   } catch {
     localCredential = 'delete_failed';
   }
-  if (remoteRevocation !== 'revoked' || localCredential !== 'deleted') {
-    const error = new Error(localCredential === 'deleted'
+  if (!['revoked', 'not_attempted'].includes(remoteRevocation) ||
+      localCredential !== 'deleted' || localContext !== 'deleted') {
+    const error = new Error(loginChanged
+      ? '退出期间已产生新登录，已保留新凭证；旧凭证的服务端撤销结果请按退出信息核对。'
+      : localContext !== 'deleted'
+      ? '选店记录清理未完成；本机凭证清理与服务端撤销已分别尝试，请按退出结果核对。'
+      : localCredential === 'deleted'
       ? '本机个人凭证已清除，服务端会话撤销未确认；请核对授权服务状态。'
       : '本机个人凭证清理失败；请按退出结果核对本地凭证与服务端会话。');
     error.cliDetails = {
       command: 'auth.logout', server: config.server, localCredential, remoteRevocation,
+      ...(localContext === 'deleted' ? {} : { localContext }),
       ...(httpStatus === undefined ? {} : { httpStatus })
     };
     throw error;
@@ -113,7 +145,10 @@ async function logout({ env = process.env } = {}) {
 
 function status({ env = process.env } = {}) {
   const { server } = oauthConfig(env);
-  return summary(server, store.readCredential(server, env));
+  const credential = store.readCredential(server, env);
+  const choice = credentialChoice(env, credential);
+  return { ...summary(server, credential), credentialSource: choice.source,
+    environmentTokenIgnored: choice.source === 'login' && Boolean(env.ZAN_SAAS_USER_ACCESS_TOKEN) };
 }
 
 function interactive(env) {
@@ -127,17 +162,24 @@ async function refreshIfNeeded(config, env, now) {
     // Another process may have refreshed while this one waited for the lock.
     const credential = store.readCredential(key, env);
     if (!credential) return null;
-    if (!(credential.accessExpiresAt - now < dayMs)) return credential;
-    if (credential.refreshExpiresAt <= now) {
-      store.deleteCredential(key, env);
+    if (credential.reauthRequired || credential.refreshExpiresAt <= now) {
       return null;
     }
+    if (!(credential.accessExpiresAt - now < dayMs)) return credential;
+    const assertUnchanged = () => {
+      const current = store.readCredential(key, env);
+      if (!current || current.generation !== credential.generation ||
+          current.refreshToken !== credential.refreshToken) {
+        throw new AuthRequiredError('个人登录在续期期间改变，请核对当前身份后重试；未改用环境身份。');
+      }
+    };
     let tokens;
     try {
       tokens = await refreshTokens(config, credential.refreshToken);
     } catch (error) {
       if (error instanceof OAuthError && error.oauthError === 'invalid_grant') {
-        store.deleteCredential(key, env);
+        assertUnchanged();
+        store.saveCredential(key, { ...credential, reauthRequired: true }, env);
         return null;
       }
       // Keep using an access token that has not expired yet when refresh is unreachable.
@@ -145,20 +187,29 @@ async function refreshIfNeeded(config, env, now) {
       throw error;
     }
     const next = { ...credential, ...tokens };
+    assertUnchanged();
     store.saveCredential(key, next, env);
     return next;
   });
 }
 
-// Resolves the user token for one request. An explicit ZAN_SAAS_USER_ACCESS_TOKEN keeps priority so
-// existing controlled environments behave as before.
+// Select once before a request; a failed personal login never changes to another identity.
 async function resolveAccessToken(env = process.env, { now = Date.now(), loginImpl = login } = {}) {
-  if (env.ZAN_SAAS_USER_ACCESS_TOKEN) {
-    return { token: env.ZAN_SAAS_USER_ACCESS_TOKEN, source: 'env' };
+  const mode = authSource(env);
+  if (mode === 'env') {
+    if (!env.ZAN_SAAS_USER_ACCESS_TOKEN) throw new AuthRequiredError('环境凭证模式缺少 ZAN_SAAS_USER_ACCESS_TOKEN。');
+    return Object.freeze({ token: env.ZAN_SAAS_USER_ACCESS_TOKEN, ...credentialChoice(env) });
   }
   const config = oauthConfig(env);
   let credential = store.readCredential(config.server, env);
-  if (credential && Number.isFinite(credential.accessExpiresAt) &&
+  const choice = credentialChoice(env, credential);
+  if (choice.source === 'env') {
+    store.syncCredentialPresence(env);
+    return Object.freeze({ token: env.ZAN_SAAS_USER_ACCESS_TOKEN, ...choice });
+  }
+  if (credential?.reauthRequired || credential?.refreshExpiresAt <= now) {
+    credential = null;
+  } else if (credential && Number.isFinite(credential.accessExpiresAt) &&
       credential.accessExpiresAt - now < dayMs) {
     credential = await refreshIfNeeded(config, env, now);
   }
@@ -170,7 +221,9 @@ async function resolveAccessToken(env = process.env, { now = Date.now(), loginIm
     credential = store.readCredential(config.server, env);
     if (!credential) throw new AuthRequiredError('Login did not produce a credential');
   }
-  return { token: credential.accessToken, source: 'login' };
+  store.syncCredentialPresence(env);
+  return Object.freeze({ token: credential.accessToken, ...credentialChoice(
+    { ...env, ZAN_SAAS_AUTH_SOURCE: 'personal' }, credential) });
 }
 
 module.exports = {

package/src/cli/command-paths.js

@@ -101,12 +101,13 @@ function commandContract(path, command) {
   if (['schema', 'doctor', 'skills.list', 'skills.read'].includes(path)) {
     return { kind: 'system', risk: 'read', availability: 'available' };
   }
-  if (['auth.status', 'auth.whoami', 'shop.list', 'shop.current'].includes(path)) {
+  if (['auth.status', 'auth.whoami', 'shop.list', 'shop.current', 'shop.resolve'].includes(path)) {
     return { kind: 'system', risk: 'read', availability: 'available' };
   }
   // Login and logout change the local credential and the server-side session; shop use and clear
   // change the saved context.
-  if (['install', 'auth.login', 'auth.logout', 'shop.use', 'shop.clear'].includes(path)) {
+  if (['install', 'auth.login', 'auth.logout', 'shop.use', 'shop.clear',
+    'shop.session.init', 'shop.unit.use'].includes(path)) {
     return { kind: 'system', risk: 'low', availability: 'available' };
   }
   if (path === 'api') return { kind: 'raw-api', risk: 'unknown', availability: 'available' };

package/src/cli/program.js

@@ -22,9 +22,16 @@ const { commandSchema } = require('../execution/command-schema');
 const { commandContract, commandPath } = require('./command-paths');
 const { configureContextHelp, isContextHelp } = require('./context-help');
 const { configureParserPolicy } = require('./parser-policy');
+const { bindApiContext, runWithApiSession } = require('../transport/api');
 
-function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills = skillsRoot,
-  eagerDomains = false, context = contextInput(process.env) } = {}) {
+function createProgram(settings = {}) {
+  const { catalog = openRegistry(), root = nativeRoot, rootSkills = skillsRoot,
+    eagerDomains = false } = settings;
+  const injected = settings.context !== undefined;
+  let context;
+  let contextError;
+  try { context = injected ? settings.context : contextInput(process.env); }
+  catch (error) { contextError = error; context = {}; }
   const { domains, skills, businessCommandCount } = catalog.manifest;
   const domainNames = new Set(domains.map(domain => domain.name));
   const loadedDomains = new Set();
@@ -62,7 +69,7 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
   program.addCommand(createDoctorCommand(businessCommandCount));
   program.addCommand(createApiCommand());
   program.addCommand(createAuthCommand());
-  program.addCommand(createShopCommand());
+  program.addCommand(createShopCommand(undefined, { context: injected ? context : undefined }));
   program.addCommand(createSkillsCommand(skills, rootSkills));
   program.addCommand(createInstallCommand());
   function configureSystemErrors(command) {
@@ -83,6 +90,11 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
   program.hook('preAction', (_parent, command) => {
     if (isContextHelp(command)) return;
     const contract = commandContract(commandPath(command), command);
+    if ((['atomic', 'task'].includes(contract.kind) && !command.opts().dryRun) ||
+        contract.kind === 'raw-api') {
+      if (contextError) throw contextError;
+      bindApiContext(contextState.context);
+    }
     if (['atomic', 'task'].includes(contract.kind)) {
       const details = commandSchema(command)?.error?.properties?.details;
       const stages = details?.properties?.stage?.enum;
@@ -112,7 +124,7 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
 快速开始：
   1. 登录：zan-saas auth login，按提示在浏览器完成授权
   2. 查看当前店铺：zan-saas shop current；已有有效上下文时沿用
-  3. 需要选店时：zan-saas shop list，按用户指定的店名或选择执行 zan-saas shop use <kdtId>
+  3. 宿主会话先 shop session init；账号选店用 shop use，连锁内切换用 shop unit use，临时查询用 shop resolve
   4. 阅读使用指引：zan-saas skills read zan-saas
 
 查询命令：
@@ -128,6 +140,10 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
   if (eagerDomains) {
     for (const domain of domains) loadDomain(domain.name);
   }
+  const parseAsync = program.parseAsync;
+  program.parseAsync = function (...args) {
+    return runWithApiSession(() => parseAsync.apply(this, args));
+  };
   return program;
 }
 

package/src/commands/native/access/commands.index.json

@@ -9,7 +9,7 @@
       "availability": "available",
       "at": "all",
       "module": "access/role/list/command.js",
-      "fingerprint": "1f1a25bdb5f2252635920dd6f154e7692cefbe5c37bf5c164aff4c0c73a23313"
+      "fingerprint": "55180dff4d111eee0ae67c4987b71a5ebe0557061228774a5cc9f0b88880d8aa"
     },
     {
       "path": "access.staff-perms.get",

package/src/commands/native/benefit/card-definition/list/command.js

@@ -64,14 +64,15 @@ function createCommand({ context } = {}) {
       .choices(['json', 'pretty']).default('json'))
     .option('--dry-run', '本地预览店铺核验和单页查询，不读凭证、不联网')
     .addHelpText('after', `
-total 只描述本次筛选的接口总数，不保证跨页快照；按 nextPageNo 继续并保留店铺、筛选和容量。
+total 只描述本次筛选的接口总数，不保证跨页快照；按 nextPageNo 继续并保留店铺和筛选。
 nextPageNo=null 不能单独解释为结束；windowLimitReached=true 表示达到页码上限，仍有后续。
 时间点统一输出北京时间 YYYY-MM-DD HH:mm:ss.SSS，字段声明的业务哨兵保留。
-输出 data.cards 和 data.pagination（含 total、nextPageNo、windowLimitReached），容量使用实际响应，不自动翻页或重试。
+输出 data.cards 和 data.pagination（含 total、nextPageNo、windowLimitReached），不自动翻页或重试。
+分页仅支持 --page-no；页容量由服务端决定，不支持 --page-size。
 仅查询商家卡定义，不表示客户持卡、发卡资格或详情权益；不按名称、类型或状态过滤。
 hasMore 表示是否还有下一页；空页或短页不表示耗尽，不承诺跨页快照。
 服务端最多允许 100 页；第 100 页仍有 hasMore=true 时不能继续遍历，不请求第 101 页。
-不提供 --name、--page-size 或 scan；最多一次店铺核验与一次业务请求。
+不提供 --name 或 scan；最多一次店铺核验与一次业务请求。
 真实执行需有效四字段上下文和同店授权凭证；店铺核验不证明员工 OAuth。
 支持微商城单店、零售单店、有赞连锁 D 总部/网店/合伙人，不承诺教育多校区总部。
 契约：zan-saas schema benefit.card-definition.list

package/src/commands/native/benefit/card-definition/list/schema.json

@@ -680,7 +680,7 @@
     "diagnosticsVersion": 2
   },
   "notes": [
-    "每次只查询一页权益卡定义，默认第 1 页，最大第 100 页；保留返回顺序和禁用卡。",
+    "每次只查询一页权益卡定义，默认第 1 页，最大第 100 页；页容量由服务端决定，不支持 --page-size。保留返回顺序和禁用卡。",
     "pageSize 为本次实际页容量，returned 为本次卡定义条数；不按空页或短页判断结束。第 100 页仍有更多时不能继续第 101 页，也不能宣称全量。",
     "可选字段缺失保持省略，已选字段 null 或错型失败；保留空字符串和 false。",
     "支持微商城单店、零售单店、连锁 D 总部、网店及合伙人，不承诺跨页快照。",

package/src/commands/native/benefit/commands.index.json

@@ -18,7 +18,7 @@
       "availability": "available",
       "at": "all",
       "module": "benefit/card-definition/list/command.js",
-      "fingerprint": "7ae054562f154e27f37ac58a06c547cde7ee3457c7382a1d3086d93e7976f4cd"
+      "fingerprint": "6e1e404d0773b8360796d76c850f5913b0db5cf17556625bccb3bc1a90a4ef48"
     },
     {
       "path": "benefit.card-grant.list",
@@ -45,7 +45,7 @@
       "availability": "available",
       "at": "all",
       "module": "benefit/customer-card/list/command.js",
-      "fingerprint": "a2db429e8c0c2d46e8f74db4d1a8a6e862670cb5340038ac8946769d26c12b1e"
+      "fingerprint": "99950d67fbfed296117eb6ad44be1fb6bae4875128847757ebd958c38a570189"
     }
   ]
 }

package/src/commands/native/benefit/customer-card/list/command.js

@@ -66,6 +66,7 @@ function createCommand({ context } = {}) {
     .addHelpText('after', `
 当前接口未提供可靠的匹配总数，因此省略 total，hasMore 为 null、nextPageNo 为 null，不自动续页。
 返回 data.customerCards 和 data.pagination；returned 为本次客户持卡条数。
+分页仅支持 --page-no；页容量由服务端决定，不支持 --page-size。
 cardNo 是完整字符串实例号；cardAlias 仅关联定义，不按定义合并持卡。
 保留源 cardState；时间点统一为北京时间 YYYY-MM-DD HH:mm:ss.SSS，包括 9999 年永久哨兵。
 空页不证明耗尽；all 不保证删除历史完整或跨页快照。

package/src/commands/native/benefit/customer-card/list/schema.json

@@ -721,7 +721,7 @@
     "diagnosticsVersion": 2
   },
   "notes": [
-    "固定一个店铺和客户，每次读取一页持卡实例，默认第 1 页；页内卡号唯一，容量取本次结果。",
+    "固定一个店铺和客户，每次读取一页持卡实例，默认第 1 页；页内卡号唯一，页容量由服务端决定，不支持 --page-size。",
     "--status available 查询可用卡，all 查询返回范围内所有状态；all 不保证已删除历史完整或跨页快照。",
     "只返回模型中的五个实例字段，不返回客户资料，不按日期推算状态；缺必需字段、null 或错型整体失败。",
     "支持微商城单店、零售单店、连锁 D 总部、网店及合伙人。",

package/src/commands/native/customer/commands.index.json

@@ -45,7 +45,7 @@
       "availability": "available",
       "at": "all",
       "module": "customer/customer-tag/list/command.js",
-      "fingerprint": "60e6f754b729a536d83aa3c01a5f0069a2bdb3d927129cdc4497e6f04cff2b47"
+      "fingerprint": "9847ca5a4011dc084d074f434c0cd4ad24633e12fe6f79395a1dfb173927bd0b"
     },
     {
       "path": "customer.segment.list",

package/src/commands/native/customer/customer-tag/list/command.js

@@ -3,7 +3,7 @@
 const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
 
 const { Command } = require('commander');
-const { requestApi, ApiConfigurationError } = require('../../../../../transport/api');
+const { requestApi, snapshotApiEnvironment, ApiConfigurationError } = require('../../../../../transport/api');
 const { validateCommandValue } = require('../../../../../execution/command-schema');
 const schema = require('./schema.json');
 
@@ -47,7 +47,7 @@ async function listCustomerTags(options, context) {
   }
   let response;
   try {
-    response = await requestApi(request);
+    response = await requestApi(request, await snapshotApiEnvironment(undefined, input.kdtId));
   } catch (error) {
     if (error instanceof ApiConfigurationError) throw failure('configuration', 'configuration');
     throw failure('transport', 'request', 'unknown');

package/src/commands/native/member/commands.index.json

@@ -36,7 +36,7 @@
       "availability": "available",
       "at": "all",
       "module": "member/level/get/command.js",
-      "fingerprint": "75de5b4aeab1b821d50cbb285011f9dfe06fbc94cecb0d74c98768ce8d74ac0a"
+      "fingerprint": "23c8774db6b4525aa8fc978babee0b64da63498f21a0e261f06fa63c7ffaa78d"
     },
     {
       "path": "member.level.list",

package/src/commands/native/org/commands.index.json

@@ -9,7 +9,7 @@
       "availability": "available",
       "at": "shop",
       "module": "org/staff/get/command.js",
-      "fingerprint": "0e6c6fd91988b916f4d5690677c712059ec65f7d6ce003eed7d7192ce61f6d96"
+      "fingerprint": "e73deac7efdda9b214eca98fea4e1d71d44d5a82e8b6cf71126f337c5b5b0a33"
     },
     {
       "path": "org.staff-role.get",
@@ -18,7 +18,7 @@
       "availability": "available",
       "at": "shop",
       "module": "org/staff-role/get/command.js",
-      "fingerprint": "cfa719f5122449c0a57e5db59bfd760d17d717f95088c9d886586b53304a7041"
+      "fingerprint": "b5c0e152bc037639379c99eac78a26ed716f5e7fbddd5bc0e485011a4d05b22b"
     },
     {
       "path": "org.unit.get",
@@ -27,7 +27,7 @@
       "availability": "available",
       "at": "all",
       "module": "org/unit/get/command.js",
-      "fingerprint": "d11775de4f1c6d7500310c3f8b373bee7e829ab5afe586ae617037571b4d0597"
+      "fingerprint": "4e4a8b3143a619cc50c80afd33bef1d42bd68896abc3bc7f250be26911be3a68"
     },
     {
       "path": "org.unit.list",
@@ -36,7 +36,7 @@
       "availability": "available",
       "at": "hq",
       "module": "org/unit/list/command.js",
-      "fingerprint": "6bee5cdcffb1893319280f50f9b49e752d16dbadcae5413bce3bbfcf476a9fc6"
+      "fingerprint": "6b1636404484b8d0823d04fe1b3ee4d8e28afc91b6e1a6489264f84fe5f137bf"
     }
   ]
 }

package/src/commands/system/api.js

@@ -32,7 +32,7 @@ function createApiCommand() {
     .option('--yes', '确认本次请求的未知副作用并发送')
     .addHelpText('after', `
 目标可以是已登记或未登记的 API，不接收任意 URL。
-默认先使用 auth login 保存的个人凭证；受控环境配置 ZAN_SAAS_USER_ACCESS_TOKEN 时使用环境凭证。
+默认优先使用 auth login 保存的个人凭证；无个人记录时使用环境token。明确使用环境身份配置 ZAN_SAAS_AUTH_SOURCE=env。
 发送须 --yes，仅确认未知副作用，不证明服务端授权。
 退出0、HTTP 2xx 和 sent=true 只说明收到响应，不证明业务成功、异步完成或写入完成。
 body 是脱敏后的原始文本；即使 HTTP 200 正文含 success=false，也不按业务失败改变退出码。

package/src/commands/system/auth.js

@@ -19,23 +19,33 @@ function localTime(iso) {
 }
 
 const cloudAccountHint = '有赞云账号开通未确认，不影响本次个人登录。请先核对账号接口状态。';
+function credentialLine(value) {
+  if (value.credentialSource === 'login') {
+    return `默认使用个人登录凭证${value.environmentTokenIgnored ? '，已忽略环境 token' : ''}。`;
+  }
+  if (value.credentialSource === 'env') return '本次配置使用环境 token；个人登录状态与环境凭证有效性分别判断。';
+  return value.credentialSource === 'missing' ? '当前没有选中的请求凭证。' : '';
+}
 
 const text = {
   login: value => {
     const lines = [value.refreshExpiresAt
       ? `登录成功，凭证有效期至 ${localTime(value.refreshExpiresAt)}。` : '登录成功。'];
     if (value.cloudAccount?.ensured === false) lines.push(cloudAccountHint);
+    if (credentialLine(value)) lines.push(credentialLine(value));
     lines.push(value.shopId ? `当前店铺上下文：kdtId ${value.shopId}。` : '当前没有有效的店铺上下文。',
       shopSelectionHint);
     return lines.join('\n');
   },
   status: value => {
-    if (!value.loggedIn) return `未登录（${value.server}）。执行 zan-saas auth login 登录。`;
+    if (!value.loggedIn) return `未登录（${value.server}）。执行 zan-saas auth login 登录。` +
+      (credentialLine(value) ? `\n${credentialLine(value)}` : '');
     const lines = [`已登录（${value.server}）`];
     if (value.loginAt) lines.push(`登录时间：${localTime(value.loginAt)}`);
     if (value.refreshExpiresAt) lines.push(`有效期至：${localTime(value.refreshExpiresAt)}`);
     if (value.shopId) lines.push(`当前店铺：${value.shopId}`);
     else lines.push('当前没有有效的店铺上下文。');
+    if (credentialLine(value)) lines.push(credentialLine(value));
     lines.push(shopSelectionHint);
     return lines.join('\n');
   },
@@ -83,7 +93,8 @@ function createAuthCommand(impl = defaults) {
 --no-browser 只跳过自动打开浏览器，仍等待授权回调并保存个人凭证，默认超时5分钟。
 人机交接：Agent 启动命令并把输出的登录地址交给用户；用户在浏览器确认后，Agent 等待本命令回调，再执行 zan-saas auth status 确认。用户取消或超时后重新执行本命令。
 登录成功后执行 zan-saas shop current 查看当前店铺。
-首次选店或需要切店时，先执行 zan-saas shop list，由用户选定 kdtId，再执行 zan-saas shop use <kdtId>。
+宿主会话首次使用执行 shop session init，恢复时加 --resume；账号选店、连锁组织切换及本次临时查询按共享指引分别处理。
+默认优先使用已保存的个人凭证；仅受控调用明确配置 ZAN_SAAS_AUTH_SOURCE=env 时使用环境 token。
 执行 zan-saas shop current 确认实际生效的店铺，再开始业务查询；切店无需重新登录。
 登录后尝试开通有赞云账号，未确认开通时不影响本次个人登录，应核对账号接口状态。
 浏览器授权完成后仍须成功换取并保存凭证；本命令失败时停止，不进入选店或业务查询。

package/src/commands/system/contracts.js

@@ -2,6 +2,7 @@
 
 const { attachCommandSchema } = require('../../execution/command-schema');
 const { parserErrorModel } = require('../../execution/parser-error');
+const shopModels = require('./shop-contracts');
 
 function object(properties, required = Object.keys(properties)) {
   return { type: 'object', additionalProperties: false, required, properties };
@@ -83,9 +84,11 @@ const skill = object({
 const serverField = { type: 'string', description: '授权服务地址的 origin，默认生产环境，ZAN_SAAS_OAUTH_BASE_URL 可覆盖；凭证按它分开保存。' };
 const time = { type: ['string', 'null'], description: 'ISO 8601 时间，服务端未返回有效期时为 null。' };
 const credentialStatus = object({
-  loggedIn: { type: 'boolean', description: '本机保存个人凭证且已知刷新有效期未到期；未知有效期时保留已有登录记录。不表示环境覆盖凭证或服务端权限有效。' },
+  loggedIn: { type: 'boolean', description: '本机个人登录未标记需要重新登录，且已知刷新有效期未到期；未知有效期时保留已有记录。不表示环境token或服务端权限有效。' },
   server: serverField,
-  clientId: text, tool: text, loginAt: time, accessExpiresAt: time, refreshExpiresAt: time
+  clientId: text, tool: text, loginAt: time, accessExpiresAt: time, refreshExpiresAt: time,
+  credentialSource: { enum: ['login', 'env', 'missing'], description: '按当前配置选中的凭证来源：个人登录、环境token或缺失。离线状态不证明服务端有效。' },
+  environmentTokenIgnored: { type: 'boolean', description: '已选个人登录且同时存在环境token时为true；环境token不会覆盖该登录。' }
 }, ['loggedIn', 'server']);
 const shopIdField = {
   type: ['string', 'null'], description: '业务命令当前使用的店铺 ID；没有有效上下文时为 null。'
@@ -108,7 +111,7 @@ const savedShop = object({
   context: { $ref: '#/definitions/context' }, shopName: { type: ['string', 'null'] }
 });
 const accountNote = '调用账号接口网关，不需要店铺；默认生产环境，ZAN_SAAS_ACCOUNT_API_BASE_URL 可覆盖，token 规则与业务命令相同。';
-const contextNote = '上下文优先级：环境变量 ZAN_SAAS_CONTEXT（即使无效）高于 shop use 保存的店铺；按授权服务地址分开保存。';
+const contextNote = '上下文优先级：显式程序注入、ZAN_SAAS_CONTEXT、宿主会话保存位置；无会话ID时使用本机共享选择。无效显式输入不回退。';
 
 const contracts = {
   install: {
@@ -214,7 +217,7 @@ const contracts = {
       'token 写入 ~/.zan-saas/credentials.json（权限 0600），按授权服务地址分开保存；输出不含 token。',
       '用户取消或超时（5 分钟）时失败退出，不自动重试。',
       '登录后用短超时尝试开通有赞云账号，未确认时只记录 ensured: false，不因此要求重新登录。',
-      '登录成功后用 shop current 查看当前店铺；首次选店或切换时用 shop list 查候选，按用户选择执行 shop use <kdtId>，再用 shop current 核对实际生效的上下文。',
+      '登录成功后按宿主生命周期初始化或恢复会话，再用 shop current 查看实际位置。账号选店、连锁内切换和临时目标分别读取 shop use、shop unit use、shop resolve 契约。',
       '浏览器授权完成不代表本命令成功；换取凭证失败时未保存新凭证，停止后续选店和业务请求，按错误核查版本、配置及授权服务路由。'
     ]
   },
@@ -232,8 +235,9 @@ const contracts = {
         server: serverField,
         localCredential: { enum: ['deleted', 'delete_failed'],
           description: 'deleted 表示当前个人凭证已在本机清除或已不存在；delete_failed 表示本地清理未成功。' },
-        remoteRevocation: { enum: ['revoked', 'failed', 'unknown'],
-          description: 'revoked 已取得撤销成功响应；failed 撤销接口返回失败，不推断会话仍有效；unknown 请求或响应未能确认。' },
+        remoteRevocation: { enum: ['revoked', 'failed', 'unknown', 'not_attempted'],
+          description: 'revoked 已确认撤销；failed 接口拒绝；unknown 无法确认结果；not_attempted 表示没有个人凭证可撤销。' },
+        localContext: { enum: ['delete_failed'], description: '选店记录清理失败时出现；凭证清理与远端撤销仍已分别尝试。' },
         httpStatus: { type: 'integer', minimum: 100, maximum: 599,
           description: '仅取得撤销接口失败 HTTP 响应时出现，不回显响应正文。' }
       }, ['command', 'server', 'localCredential', 'remoteRevocation'])
@@ -295,17 +299,17 @@ const contracts = {
     ]
   },
   'shop.use': {
-    input: object({ kdtId: id }),
-    output: object({
+    input: object({ kdtId: id, sessionOnly: { type: 'boolean', description: '只更新本会话，不更新最近位置；需要会话ID。' } }, ['kdtId']),
+    output: { oneOf: [object({
       context: { $ref: '#/definitions/context' }, shopName: { type: ['string', 'null'] },
       overriddenByEnv: { type: 'boolean', description: '为 true 时 ZAN_SAAS_CONTEXT 已设置，业务命令仍以它为准。' }
-    }),
+    }), shopModels.chosenOutput('use_root')] },
     definitions: { context },
     notes: [
       accountNote,
       '先查询当前用户，再在其店铺列表中确认该店铺，只接受总部或单店；hq 与 shopId 都取该店铺 ID。',
-      '当前用户在该店铺的员工账号已停用时拒绝；员工状态查询失败不阻止选择。',
-      '上下文写入 ~/.zan-saas/context.json（权限 0600），不含凭证；本地上下文不是权限证明，服务端仍校验。',
+      '当前用户在该店铺的员工账号已停用时拒绝。共享模式员工状态查询失败保留旧兼容行为；会话模式要求核实成功，失败不保存选择。',
+      '无会话ID时写入 ~/.zan-saas/context.json；会话模式独立保存并默认更新供新会话继承的位置。上下文不含凭证，不证明权限。',
       '首次选择与切换店铺均使用本命令，无需重新登录；保存后用 shop current 确认实际店铺，overriddenByEnv 为 true 时不能声称当前上下文已切换。',
       contextNote
     ]
@@ -313,19 +317,23 @@ const contracts = {
   'shop.current': {
     input: empty,
     output: object({
-      source: { enum: ['env', 'saved', 'missing'] },
+      source: { enum: ['env', 'saved', 'missing', 'program'] },
       status: { enum: ['ready', 'invalid', 'missing'] },
       context: nullableContext,
       saved: { anyOf: [savedShop, { type: 'null' }] },
-      requestShopId: { type: ['string', 'null'], description: '环境变量 ZAN_SAAS_KDT_ID 的有效值；未设置或无效时为 null。不代表所有命令的最终请求店铺。' }
-    }),
+      requestShopId: { type: ['string', 'null'], description: '环境变量 ZAN_SAAS_KDT_ID 的有效值；未设置或无效时为 null。不代表所有命令的最终请求店铺。' },
+      binding: shopModels.binding,
+      selection: { anyOf: [shopModels.selection, { type: 'null' }] }
+    }, ['source', 'status', 'context', 'saved', 'requestShopId']),
     definitions: { context },
     notes: ['只读本地文件和环境变量，不联网。requestShopId 是环境变量值；部分命令按其目标店铺设置请求头，具体以命令契约为准。', contextNote]
   },
   'shop.clear': {
-    input: empty,
-    output: object({ cleared: { type: 'boolean', description: '本地有保存的店铺并已删除时为 true。' }, server: serverField }),
-    notes: ['只删除当前授权服务地址下保存的店铺，不联网，不影响 ZAN_SAAS_CONTEXT。']
+    input: object({ recent: { type: 'boolean', description: '同时清除该账号环境的最近位置；仅会话模式支持。' } }, []),
+    output: object({ cleared: { type: 'boolean', description: '已清除选中的店铺；重复清除为false。' }, server: serverField,
+      binding: shopModels.binding, currentChanged: { type: 'boolean' }, recentChanged: { type: 'boolean' } },
+    ['cleared', 'server']),
+    notes: ['会话模式保留cleared记录，避免重新继承；默认不影响其他会话或最近位置。原文件内改写，不删除或替换上下文文件。']
   },
   'skills.list': {
     input: empty,
@@ -356,7 +364,7 @@ const contracts = {
     }),
     notes: [
       '按明确的 API 名和版本发送 POST，可以是已登记或未登记的接口。风险未知，发送需 --yes；不继承领域命令的对象校验、风险分级和业务结果保证。',
-      '默认发送到生产开放 API 网关，ZAN_SAAS_API_BASE_URL 可覆盖；默认使用 auth login 保存的凭证，受控环境配置 ZAN_SAAS_USER_ACCESS_TOKEN 时使用环境凭证；不接受任意目标 URL。',
+      '默认发送到生产开放 API 网关，ZAN_SAAS_API_BASE_URL 可覆盖。默认优先使用已存个人登录，仅无个人记录时使用环境token；显式 ZAN_SAAS_AUTH_SOURCE=env 可选择环境凭证，不接受任意目标 URL。',
       '退出0、HTTP 2xx 和 sent=true 只表示收到响应；即使正文报告业务失败也不改变退出码，不证明业务成功或写入完成。超时或断连时结果未知，不自动重试。',
       '不提供 --dry-run，不自动应用业务金额或日期转换。'
     ]
@@ -364,7 +372,7 @@ const contracts = {
 };
 
 function withSystemSchema(command, name) {
-  const schema = { schemaVersion: 1, error, ...contracts[name] };
+  const schema = { schemaVersion: 1, error, ...(contracts[name] || shopModels.contracts[name]) };
   schema.error = { anyOf: [schema.error, structuredClone(parserErrorModel)] };
   attachCommandSchema(command, schema);
   return command;