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

package/bin/zan-saas-cli.js

@@ -2,22 +2,19 @@
 'use strict';
 
 const { createProgram } = require('../src/cli/program');
-const { runWithApiSession } = require('../src/transport/api');
 const { finalizeError } = require('../src/execution/error-details');
 const { visibleCommands } = require('../src/commands/system/schema');
 const { commandSchema } = require('../src/execution/command-schema');
 
 let program;
-Promise.resolve().then(() =>
-  runWithApiSession(() => {
-    program = createProgram();
-    if (process.argv.length === 2) {
-      program.outputHelp();
-      return undefined;
-    }
-    return program.parseAsync(process.argv);
-  })
-).catch(error => {
+Promise.resolve().then(() => {
+  program = createProgram();
+  if (process.argv.length === 2) {
+    program.outputHelp();
+    return undefined;
+  }
+  return program.parseAsync(process.argv);
+}).catch(error => {
   if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) return;
   if (error.code === 'commander.help' && error.exitCode === 0) return;
   const registered = program && visibleCommands(program)

package/internal/registry/manifest.json

@@ -10,7 +10,7 @@
       "indexFile": "access/commands.index.json",
       "commandCount": 2,
       "indexSize": 652,
-      "indexSha256": "77d7b2ec53cfff2a40f6dee4adb5501f12cf9681a09e7e759c78570feff46546"
+      "indexSha256": "0b87b02e700ae06f5835f54599259a0d7c1739a7cb9f83f7db370010a6872bce"
     },
     {
       "name": "aftersale",
@@ -50,7 +50,7 @@
       "indexFile": "customer/commands.index.json",
       "commandCount": 10,
       "indexSize": 3042,
-      "indexSha256": "f978a5016e0f30f32b4808d05f258992e1e162cff4c5448bd85672dc266a97b0"
+      "indexSha256": "3aa80cf1681c76e7d720f7f70c411850b53d8d312b5468124caa7cfa1a987652"
     },
     {
       "name": "fulfillment",
@@ -90,7 +90,7 @@
       "indexFile": "member/commands.index.json",
       "commandCount": 6,
       "indexSize": 1811,
-      "indexSha256": "62618e138aa9ef06743cfc9b3c1a08fd40883d7ebf8bc058e880f1b8a4a1bb65"
+      "indexSha256": "3f122369a09e91ac0d1ab8981bffef4d7a05ce99b8f4b0ae6cbd5b7588a9679c"
     },
     {
       "name": "order",
@@ -106,11 +106,11 @@
       "name": "org",
       "description": "组织：组织资料、员工与角色关联",
       "skill": "zan-saas-org",
-      "fingerprint": "e2584b58e4c8ed6b2c080096e7e0fe1ba9c7f5297a1854d49f939749eef848c6",
+      "fingerprint": "a37293793a4944a5afa4ea2cf85168852f93b876e8e57d7f7b8d7b2a49e75ce0",
       "indexFile": "org/commands.index.json",
       "commandCount": 4,
       "indexSize": 1185,
-      "indexSha256": "553820c277b0965b1a4e9d485290588e5939ca5a4b7986ea66501ceb5197f17f"
+      "indexSha256": "88abc0f5b6605a408ef88dd969f6ed2bb4473b7fa36001b2036c40d68e8a5173"
     },
     {
       "name": "points",
@@ -165,7 +165,7 @@
         "SKILL.md",
         "references/host-entry.md"
       ],
-      "fingerprint": "6fd2bb9b078420651fc470a57b64a7a64e16e565ee5ca5f29445348a5a342031"
+      "fingerprint": "5b40c6bec46af43e31ea6406475c59afae705e9cc247640deafc4626b6c599b1"
     },
     {
       "name": "zan-saas-shared",
@@ -175,9 +175,10 @@
       "files": [
         "SKILL.md",
         "references/authentication.md",
+        "references/shop-context.md",
         "references/value-processing.md"
       ],
-      "fingerprint": "5e4b2681b29e7e383fe0a39ca91327f7b9f00cded29c8f4da30eef8daca9dab0"
+      "fingerprint": "05045a2660b7801297f0883650aabc240fda7b6115b7cbe6a0edbdf43b1e2676"
     },
     {
       "name": "zan-saas-access",
@@ -359,7 +360,7 @@
         "references/unit-get.md",
         "references/unit-list.md"
       ],
-      "fingerprint": "1ba9227cd426f9770a57c87fa335e5cac87f4c0e8d7d65f62437ab3bcbf1fa47"
+      "fingerprint": "2732c7e06c009a15f5b00fb028e72ceb518e1f5b1618c58523310962e14e1d4e"
     },
     {
       "name": "zan-saas-points",

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@youzan-cloud/zan-saas-cli",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@youzan-cloud/zan-saas-cli",
-      "version": "0.1.0-beta.4",
+      "version": "0.1.0-beta.7",
       "license": "MIT",
       "dependencies": {
         "ajv": "8.20.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youzan-cloud/zan-saas-cli",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.7",
   "description": "Youzan SaaS CLI preview",
   "license": "MIT",
   "engines": {

package/skills/zan-saas/SKILL.md

@@ -11,13 +11,13 @@ Agent 负责运行命令、定位对象和解释结果。用户只需完成浏
 
 需要登录时，Agent 运行 `zan-saas auth login` 并把输出的授权地址交给用户；用户在浏览器确认授权，Agent 等待命令成功，再运行 `zan-saas auth status`。浏览器显示授权完成但命令失败时，按错误核查并停止，不将已有凭证状态当作本次登录成功。用户取消或授权超时后，需要继续时重新运行登录。
 
-先运行 `zan-saas shop current` 查看当前店铺。已有有效上下文且用户没有要求切店时继续使用，不重复询问。用户明确指定店名时，Agent 用 `zan-saas shop list` 查找可选店铺。核对相关候选和分页后，只有店名唯一匹配时才用结果中的 `kdtId` 执行 `zan-saas shop use <kdtId>`。同名或含义不明确时，展示店名和类型让用户区分，不从名称片段推定目标。
+先读取 `zan-saas skills read zan-saas-shared`，按公共规则确定会话位置及本次任务范围。商家所说的“店铺”可能指账号下的单店或连锁，也可能指连锁内部的店铺；明确目标后区分持久切换和本次临时查询，再选择命令。
 
-没有上下文且用户没有指定店铺时，展示候选店名供选择。即使只有一个候选，也简短询问“使用某某店吗？”。用户可以按店名或本次展示的序号回答，Agent 保留候选与 ID 的对应关系，无需用户理解或输入 `kdtId`。不默认选第一家，也不把未查完的一页当成全部候选。
+宿主提供稳定会话标识时，新会话首次业务使用前初始化，恢复时使用原标识及恢复模式。需要初始化、恢复、临时查询或处理覆盖时，读取 `zan-saas skills read zan-saas-shared references/shop-context.md`。已就绪且用户没有要求切换时沿用，不重复询问。
 
 店铺列表的 `total` 是员工停用过滤前的匹配总数，未知时为 `null`。`nextPageNo` 非空时，保留名称、业务线、容量及 `--all` 等选项，用 `--page-no` 继续；`hasMore=null` 表示是否还有后续未知。不要因本页候选少或为空就认定查完；`windowLimitReached=true` 时停止翻页，缩小筛选，不宣称已查全。
 
-选店后用 `zan-saas shop current` 核对实际生效的店铺和来源。切店无需重新登录，浏览器中的店铺选择不改变 CLI 上下文。账号接口路由或 OAuth 地址错误时，按共享指引的[认证排查](../zan-saas-shared/references/authentication.md)核查版本、配置和服务端路由，停止后续请求。`whoami`、`shop current`、`help`、`schema`、`--dry-run`、业务请求和错误判断由 Agent 完成。
+选店后用 `zan-saas shop current` 核对实际位置和来源。宿主未提供稳定会话标识时使用本机共享选择，不能声称会话隔离。切店无需重新登录，浏览器中的店铺选择不改变 CLI 上下文。账号路由或 OAuth 地址错误按共享指引的[认证排查](../zan-saas-shared/references/authentication.md)处理。
 
 ## 选择当前能力
 

package/skills/zan-saas/references/host-entry.md

@@ -23,3 +23,11 @@ description: 有赞 SaaS 产品的命令行工具入口。用户需要查询有
 宿主侧只保存这个轻量入口，不复制整份领域知识。CLI 升级后重新读取同版指引；宿主不支持按需读取时，需要显式安装匹配版本的静态副本。
 
 重复安装只更新本项目管理且未被手工修改的入口；同名其他 Skill 保留并报错。安装不执行登录、选店或业务请求。完成后在宿主技能列表确认 `zan-saas` 已启用，再打开新会话。
+
+## 会话选店接入
+
+安装成功只表示 CLI 和入口文件已就绪。会话隔离还要求宿主从可信元数据取得稳定标识及新建/恢复状态，每次调用注入 `ZAN_SAAS_SESSION_ID`。恢复复用标识，新建生成新标识；已接入的启动器漏传标识时应拒绝业务调用。
+
+新会话先初始化，恢复使用 `shop session init --resume`。业务任务固定 current 或 resolve 返回的四字段 context，并在每次调用显式注入；任务结束丢弃。位置管理命令使用会话环境，不携带旧任务覆盖。具体步骤读取 `zan-saas skills read zan-saas-shared references/shop-context.md`。
+
+宿主未具备或尚未验证这些能力时，说明使用本机共享模式，不把入口 Skill 的安装或模型记住店铺当作会话隔离。

package/skills/zan-saas-org/SKILL.md

@@ -17,6 +17,10 @@ description: 查询当前组织资料、总部下级组织、微商城单店员
 
 组织角色描述组织在体系中的身份，员工角色关联描述授角事实，角色定义目录描述有哪些角色，员工权限点描述本次可读权限。四者分别判断，角色名称不能推算权限或可授予性；业务线也不证明店铺类型。
 
+商家在连锁内说的“店铺”通常指组织单元，先核对所属连锁和组织角色。账号层店铺入口由公共 `shop list` 发现，本域读取组织事实；当前位置由公共选店机制管理。需要内部切换、临时查询其他组织，或在分店浏览同连锁下级候选时，读取 `zan-saas skills read zan-saas-shared references/shop-context.md`。
+
+组织详情仍固定当前任务上下文；不能把下级 ID 直接代入原上下文的详情参数。准备其他组织的任务上下文后，所选叶子的产品、位置和权限限制仍适用。能够切到分店不扩大微商城单店员工入口的支持范围。
+
 ## 按目标选择命令
 
 | 用户目标 | 命令入口与读取条件 |

package/skills/zan-saas-shared/SKILL.md

@@ -15,15 +15,26 @@ description: zan-saas 跨领域公共使用规则。首次调用或 CLI 版本
 
 需要登录时使用 `zan-saas auth login`，本地查看已存凭证状态使用 `zan-saas auth status`；用户要求退出时使用 `zan-saas auth logout`。先读取相应 help/schema，登录需要用户在浏览器中完成授权，退出尝试撤销当前授权服务下的个人会话并清理本机凭证。
 
-认证统一由公共入口与传输层处理，领域命令不选择凭证或决定登录、续期策略。普通使用先通过 `zan-saas auth login` 获取本机个人凭证；受控环境显式注入 `ZAN_SAAS_USER_ACCESS_TOKEN` 时，实际 API 请求优先使用环境凭证，否则使用本机凭证，并在需要时自动续期。同一次命令从首个实际请求开始固定调用环境和凭证；参数拒绝、发现及预览不会触发认证。
+认证统一由公共入口与传输层处理，领域命令不选择凭证或决定登录、续期策略。普通使用通过 `zan-saas auth login` 保存个人登录，后续默认优先使用该个人凭证并按需续期；环境中存在 `ZAN_SAAS_USER_ACCESS_TOKEN` 不会覆盖已保存的个人登录。没有个人登录记录时才使用环境 token；受控调用明确要求环境身份时配置 `ZAN_SAAS_AUTH_SOURCE=env`。个人登录失效或续期被拒绝时重新登录，不自动切换环境身份。同一次命令从首个实际请求开始固定调用环境、凭证及来源；参数拒绝、发现及预览不会触发认证。
 
 缺少凭证时，交互终端可进入公共登录流程，非交互环境返回登录指引。不索取聊天中的 token，也不读取旧 `youzan-cli` 配置。`auth status` 只检查本地保存状态，不证明环境覆盖凭证有效、业务权限已获准或目标店铺匹配。登录和续期不能作为业务请求失败后的自动重放理由。
 
 需要配置、自定义授权环境、判断续期、退出结果、请求计数，或登录与选店收到 OAuth HTTP 404、账号网关 `4003` 时，读取 [公共认证与会话](references/authentication.md)。业务命令声明的请求预算计算业务 API，不包含公共认证前置；上下文与服务端业务授权仍须分别满足。
 
-先用 `zan-saas shop current` 检查当前店铺；有效且用户未要求切店时沿用。需要设置店铺时，用 `zan-saas shop list` 查可选店铺，按用户明确的店名或选择映射到结果中的 ID，再执行 `zan-saas shop use <kdtId>`；名称匹配及歧义处理见下文“人机交接”。环境上下文可显式覆盖已保存的选择。
+商家说的“店铺”可能指账号下的单店或连锁，也可能指连锁内部的分店、网店。按本次明确限定、已确认任务范围、会话位置和真实候选依次核实；历史只作线索。账号层入口由 `shop list` 发现，连锁下级候选按组织领域指引发现。
 
-业务调用的用户上下文由入口注入，或通过 `ZAN_SAAS_CONTEXT` 提供仅含 `userId`、`hq`、`shopId`、`orgType` 的 JSON；未设置时使用 `zan-saas shop use <kdtId>` 保存的上下文，`zan-saas shop current` 可查看当前来源。`orgType` 只取 `hq` 或 `shop`；总部时 `shopId` 等于 `hq`，`shop` 时二者可以相同，单店按 `orgType: shop` 判断可用位置。员工、店铺与总部关系仍由服务端授权，不能把本地上下文当作权限证明。凭证不放进该 JSON。
+| 用户意图 | 操作 |
+| --- | --- |
+| 切到另一家单店或连锁，之后默认使用它 | `shop use`，进入根组织 |
+| 切到当前连锁内部的店铺，之后默认使用它 | `shop unit use`，保留当前连锁根 |
+| 本次查询另一家店铺 | `shop resolve` 后固定本次任务上下文 |
+| 继续当前范围且未要求切换 | 沿用已确认的位置 |
+
+新会话首次初始化继承一次最近位置，已有会话独立保持。明确切换默认更新本会话及供未来会话继承的位置；只影响本会话时按 `--session-only` 契约处理。查询和恢复不更新最近位置。需要初始化、恢复、临时执行、组织消歧或覆盖处理时，读取 `zan-saas skills read zan-saas-shared references/shop-context.md`。
+
+多次 CLI 调用属于同一任务时，开始时固定四字段上下文，逐次显式传入。对象引用保留环境、所属租户及领域需要的组织范围；改变范围后按领域契约核实。当前范围查无结果或请求失败时，结论只覆盖实际查询范围；历史同名对象不能替换本次对象或触发自动跨店补查。首次继承、切换、临时查询或旧请求返回可能造成混淆时，使用“某某连锁 / 杭州店”说明实际范围。
+
+业务调用的用户上下文由入口注入，或通过 `ZAN_SAAS_CONTEXT` 提供仅含 `userId`、`hq`、`shopId`、`orgType` 的 JSON；否则取已初始化会话位置，无会话标识时取本机共享选择。`shop current` 查看实际来源。`hq` 表示租户根，单店为自身；`shopId` 表示当前组织；`orgType` 只取 `hq/shop`，后者为受支持的非总部位置，不能据此认定单店或分店角色。凭证不放进该 JSON，组织关系与权限仍由服务端核验。
 
 业务命令的 `at` 声明为 `hq`、`shop` 或 `all`。有有效上下文时，根与领域帮助按位置展示适用命令；无有效上下文时全量展示并提示未筛选。单条帮助始终可查，schema 始终保留完整契约。命令未展示时不自动切店或改用 Raw API；真实执行仍检查位置。
 
@@ -76,9 +87,9 @@ description: zan-saas 跨领域公共使用规则。首次调用或 CLI 版本
 
 `auth login` 会输出浏览器授权地址并等待回调。Agent 把地址交给用户，用户确认后等待命令成功，再执行 `zan-saas auth status`。浏览器授权完成只代表取得授权码；命令失败时按认证错误核查并停止，已有凭证状态不能证明本次登录完成。用户取消或五分钟超时后，需要继续时重新执行登录。
 
-登录成功后先执行 `zan-saas shop current`，向用户展示当前 CLI 店铺。已有有效店铺上下文且用户未要求切店时沿用。用户明确指定店名时，Agent 查询可选店铺并核对相关候选和分页。只有店名唯一匹配时才执行 `zan-saas shop use <kdtId>`。同名或目标不明确时展示店名和类型让用户区分。没有上下文又没指定店铺时，请用户按店名或本次候选序号选择，ID 由 Agent 映射。只有一个候选时也简短确认。不默认选第一家，不要求用户理解内部 ID，不把一页唯一候选视为全账号唯一。选店后执行 `zan-saas shop current` 核对实际生效的店铺和来源。
+登录成功后按宿主生命周期初始化或恢复，再用 `shop current` 展示当前位置。无位置且用户没有指定目标时，请用户按店名或本次候选序号选择，只有一个候选也简短确认；明确名字唯一且范围无歧义时继续。ID 由 Agent 映射，不默认第一家，不把一页唯一候选视为全账号唯一。选定对象及动作后按上表执行，成功后读取实际位置。
 
-切店无需重新登录，浏览器内切店不会改变 CLI 上下文。`shop use` 的 `overriddenByEnv=true` 表示只保存了选择，实际仍由 `ZAN_SAAS_CONTEXT` 覆盖；Agent 应说明当前来源，按受控环境配置处理后再核对，不声称已经切换成功。
+切店无需重新登录，浏览器内切店不会改变 CLI 上下文。会话模式的显式覆盖冲突会拒绝切换；共享模式 `overriddenByEnv=true` 仍表示只保存、未实际生效。说明实际来源，按受控配置处理后核对，不声称切换成功。
 
 列表的 `returned` 只表示本页条数，不能当作匹配总数；`pagination.total` 表示匹配查询条件的总记录数，仅在有可靠来源时提供；省略表示未知，不能用本页条数补值。提供 `nextPageNo` 和 `windowLimitReached` 的命令中，下一页码非 null 才有已确认且合法的下一页；达到窗口上限不等于数据已读完。保留原筛选和页容量，不能从其他命令类推分页上限。
 

package/skills/zan-saas-shared/references/authentication.md

@@ -4,11 +4,15 @@
 
 ## 配置与优先级
 
-普通使用先执行 `zan-saas auth login`，读取本机保存的个人凭证。受控环境配置 `ZAN_SAAS_USER_ACCESS_TOKEN` 时，业务请求优先使用该环境凭证；否则使用本机个人凭证。默认生产 API 网关为 `https://open.youzanyun.com/api`，`ZAN_SAAS_API_BASE_URL` 可以覆盖。没有显式网关配置不等于缺少认证。
+普通使用先执行 `zan-saas auth login`。默认使用已保存的个人登录并按需续期，环境 token 不会覆盖它。仅没有个人登录记录时才使用 `ZAN_SAAS_USER_ACCESS_TOKEN`。个人登录已失效或续期被拒绝时返回重新登录指引，保留需重新登录状态，后续调用也不会悄悄换成环境身份。
+
+`ZAN_SAAS_AUTH_SOURCE` 可取 `auto`、`personal` 或 `env`。默认 auto 采用上述优先级；personal 只使用个人登录；env 是受控调用的明确选择，只使用环境 token，缺少该 token 时失败。非法配置失败，不回退其他身份。请求发出后不会因401、权限或业务错误更换凭证重放。
+
+默认生产 API 网关为 `https://open.youzanyun.com/api`，`ZAN_SAAS_API_BASE_URL` 可以覆盖。没有显式网关配置不等于缺少认证。
 
 `ZAN_SAAS_CONFIG_DIR` 可以指定凭证目录；默认是 `~/.zan-saas`。`ZAN_SAAS_OAUTH_BASE_URL` 可以指定授权服务，个人凭证按授权服务 origin 分开保存。配置目录和授权服务必须与登录时一致。
 
-业务命令的目标店铺可由 `--kdt-id` 显式指定；省略时取本次有效上下文的 shopId，两者都没有则失败。显式值非法时不回退。已有有效上下文且用户未要求切店时沿用；需要切店时，按用户明确的店名在可选店铺中唯一匹配，歧义时请用户选择，ID 由 Agent 映射。目标解析不证明权限，原有同店、总部及服务端授权校验仍适用。
+业务命令的目标店铺可由 `--kdt-id` 显式指定；省略时取本次有效上下文的 shopId，两者都没有则失败。显式值非法时不回退。目标解析不证明权限，原有同店、总部及服务端授权校验仍适用。会话位置、组织切换和临时目标执行按 [会话选店](shop-context.md) 处理。
 
 业务请求的店铺头优先取 `ZAN_SAAS_KDT_ID`，否则取环境或 `shop use` 保存的有效上下文 shopId；公共同店查询会绑定本次明确目标。店铺头、本地上下文与实际服务端授权不是同一件事，查询仍须通过各领域的目标范围检查。
 
@@ -16,7 +20,7 @@
 
 运行 `zan-saas auth login` 完成浏览器授权。`--no-browser` 只跳过自动打开浏览器，仍打印地址并等待手动授权回调，再交换与保存凭证；默认超时五分钟。
 
-本命令成功退出后才进入选店流程：用 `zan-saas shop current` 展示当前店铺；需要首次选择或切换时，用 `zan-saas shop list` 查候选，按用户本次选择执行 `zan-saas shop use <kdtId>`，再用 `zan-saas shop current` 确认实际生效的店铺和来源。切店复用当前登录凭证，浏览器切店不会改变 CLI 保存的上下文；环境上下文覆盖时，以 `shop current` 为准。
+本命令成功退出后才接续会话初始化或恢复，再用 `shop current` 核对实际位置；缺目标时按公共选店规则补齐。切店复用当前登录凭证，浏览器切店不会改变 CLI 上下文；显式覆盖以实际来源为准。
 
 首次实际 API 请求才解析认证，并为本次命令固定调用环境与已取得凭证。help、schema、参数校验拒绝和 `--dry-run` 不读取凭证文件、不触发登录或续期、不发送业务请求。
 
@@ -38,7 +42,7 @@
 
 ## 状态与退出
 
-`zan-saas auth status` 只读取当前授权服务下的本机个人凭证。loggedIn 表示本地存在记录且已知刷新有效期未过期，未知有效期时保留已有登录记录；它不联网，也不判断环境 token 或服务端权限是否有效。
+`zan-saas auth status` 离线查看当前授权服务下的个人登录和凭证选择。loggedIn 表示本地个人记录未要求重新登录且已知刷新有效期未过期；credentialSource 分别以 login/env/missing 表示按配置选择个人、环境或没有凭证。environmentTokenIgnored 为 true 表示个人登录优先，忽略了同时存在的环境 token。状态不联网，不证明实际凭证或服务端权限有效。
 
 `zan-saas auth logout` 尝试撤销当前授权服务下保存的个人会话，并清除对应本机凭证和已选店铺。它不清除或撤销环境注入的 token，不退出其他授权服务下的个人会话。没有本机凭证时返回 revoked=false，不表示外部凭证已失效。
 
@@ -48,5 +52,6 @@
 | --- | --- |
 | localCredential | deleted 表示本机记录已清除或已不存在；delete_failed 表示本地清理失败。 |
 | remoteRevocation | revoked 表示取得撤销成功响应；failed 表示撤销接口返回失败，不据此推断会话仍有效；unknown 表示请求或响应未能确认。 |
+| localContext | 仅选店记录清理失败时返回 delete_failed；凭证清理和远端撤销仍分别尝试。没有个人凭证可撤销时 remoteRevocation 为 not_attempted。 |
 
 远端撤销失败或结果未知时仍尝试本地清理。不得把非零退出理解为本机凭证一定仍在，也不因失败自动重试撤销或重放业务请求。

package/skills/zan-saas-shared/references/shop-context.md

@@ -0,0 +1,37 @@
+# 会话位置、选店与临时查询
+
+本说明用于初始化或恢复会话、区分店铺层级、切换组织、执行临时目标及处理位置冲突。先读取相关命令的同版 help/schema；正常查询沿用已就绪的位置，不需要每次初始化。
+
+## 初始化与恢复
+
+宿主须从可信会话元数据取得稳定标识，每次调用通过 `ZAN_SAAS_SESSION_ID` 注入。真正的新会话使用新标识；恢复同一会话复用原标识。标识不由商家提供，不从业务文档、工作目录、PID 或时间猜测。
+
+新会话首次业务使用前执行 `zan-saas shop session init`。已就绪时沿用继承的位置；待选店时按商家明确目标或相关候选选择。已有绑定再次初始化保持原选择。恢复执行 `zan-saas shop session init --resume`，记录缺失时说明无法恢复并请求明确选店，不改用新建模式绕过错误。
+
+`shop current` 离线查看有效来源与保存绑定，不会初始化。清除后保留清除状态，不自动继承别的会话后来选择的位置。登录账号或环境改变后重新核实身份及相应绑定。
+
+## 确定对象和动作
+
+账号下的独立店铺或连锁入口用 `shop list` 发现，切换到该入口用 `shop use`。连锁内部店铺按组织领域指引及 `org unit list` 发现；同连锁持久切换用 `shop unit use`，回总部使用已核实的根 ID。名字唯一还需所属关系与相关分页明确。
+
+只有商家明确要求后续默认切换时才保存位置。用户说“查一下另一家店”时使用 `shop resolve`，保持原会话。只要求本会话改变时，切换使用 `--session-only`。持久切换成功后用 `shop current` 核对实际生效位置。
+
+同名或跨层有歧义时，用完整名称和所属关系询问，例如“你指的是 A 连锁下的杭州分店，还是独立店铺杭州店？”不询问“租户还是组织单元”，也不要求输入根组织 ID。
+
+## 临时目标与任务快照
+
+`shop resolve <目标ID>` 解析账号层根。解析连锁内部目标时附 `--root-kdt-id <所属根ID>`。返回的 context 只用于本次任务；它不改变当前位置或最近位置。
+
+宿主把返回的四字段 context 作为每次业务调用的 `ZAN_SAAS_CONTEXT` 或程序注入值，并持续传原会话 ID。多命令任务每一步使用同一快照，不重新读取最近位置。任务结束后丢弃，无需切回原店。快照不包含 token，实际权限仍由服务端核验。
+
+当前在分店而要浏览同连锁候选时，先 resolve 已核实的根，使用临时总部上下文执行 `org unit list`，按页读取；当前会话仍为原分店。每条业务命令仍须满足自己的位置、产品和同店限制，不能直接用目标参数绕过。
+
+位置管理命令使用会话调用环境，不携带上次任务专用 context。用户受控配置的覆盖不能为使切换成功而擅自删除。
+
+切换期间已经发出的请求按原目标解释。迟到结果标明原店铺；新范围的后续步骤重新核验对象。查无结果、权限拒绝或未知结果不能用历史其他店铺的数据补答案。
+
+## 覆盖、冲突及共享模式
+
+实际来源以 `shop current` 为准。显式上下文无效不回退；会话模式显式上下文或请求头与切换目标冲突时拒绝保存。并发版本冲突先读取当前位置，再根据仍有效的明确意图处理，不自动重放业务操作。
+
+没有宿主标识时使用本机共享选店，其他会话可能影响下一次调用，不能声称会话隔离。临时查询仍可 resolve 后显式传入任务上下文。内部持久切换需要会话模式；安装入口文件不会自动提供稳定会话标识和逐次注入能力。

package/src/auth/credential-source.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { AuthConfigurationError } = require('./config');
+
+function authSource(env) {
+  const source = env.ZAN_SAAS_AUTH_SOURCE ?? 'auto';
+  if (!['auto', 'personal', 'env'].includes(source)) {
+    throw new AuthConfigurationError('ZAN_SAAS_AUTH_SOURCE 只接受 auto、personal 或 env。');
+  }
+  return source;
+}
+
+function credentialChoice(env, credential) {
+  const mode = authSource(env);
+  if (mode !== 'env' && credential) {
+    return { source: 'login', credentialRef: `login:${credential.generation || credential.loginAt || 'legacy'}` };
+  }
+  if (mode !== 'personal' && env.ZAN_SAAS_USER_ACCESS_TOKEN) {
+    const hash = createHash('sha256').update(env.ZAN_SAAS_USER_ACCESS_TOKEN).digest('hex');
+    return { source: 'env', credentialRef: `env:${hash}` };
+  }
+  return { source: 'missing', credentialRef: null };
+}
+
+module.exports = { authSource, credentialChoice };

package/src/auth/credential-store.js

@@ -3,7 +3,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { configDir } = require('./config');
+const { configDir, AuthConfigurationError } = require('./config');
+const { credentialChoice } = require('./credential-source');
 
 const fileName = 'credentials.json';
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
@@ -53,16 +54,70 @@ const readAll = env => readStore(fileName, env);
 const writeAll = (data, env) => writeStore(fileName, data, env);
 
 // Credentials are keyed by oauth origin so logins to different environments do not overwrite each other.
+function credentialDocument(env) {
+  let data;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(credentialPath(env), 'r');
+    const stat = fs.fstatSync(descriptor);
+    data = JSON.parse(fs.readFileSync(descriptor, 'utf8'));
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error();
+    return { data, metadata: { mtimeMs: stat.mtimeMs, size: stat.size, ino: stat.ino, dev: stat.dev } };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { data: {}, metadata: null };
+    throw new AuthConfigurationError('个人凭证文件损坏或不可读，请重新登录；未改用环境身份。');
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
 function readCredential(server, env = process.env) {
-  const entry = readAll(env)[server];
-  return entry && typeof entry.accessToken === 'string' && typeof entry.refreshToken === 'string'
-    ? entry : null;
+  const { data } = credentialDocument(env);
+  if (!Object.hasOwn(data, server)) return null;
+  const entry = data[server];
+  if (!entry || typeof entry.accessToken !== 'string' || !entry.accessToken ||
+      typeof entry.refreshToken !== 'string' || !entry.refreshToken) {
+    throw new AuthConfigurationError('个人凭证记录不完整，请重新登录；未改用环境身份。');
+  }
+  return entry;
+}
+
+function syncCredentialPresence(env = process.env) {
+  const filename = 'credential-state.json';
+  const { data, metadata } = credentialDocument(env);
+  const records = Object.fromEntries(Object.entries(data).map(([server, credential]) => [server, {
+    present: true,
+    credentialRef: credential && typeof credential.accessToken === 'string' &&
+      typeof credential.refreshToken === 'string'
+      ? credentialChoice({ ZAN_SAAS_AUTH_SOURCE: 'personal' }, credential).credentialRef : 'login:pending'
+  }]));
+  const next = { schemaVersion: 1, metadata, records };
+  if (JSON.stringify(readStore(filename, env)) === JSON.stringify(next)) return;
+  writeStore(filename, next, env);
+}
+
+// Offline context selection reads only this non-secret index and file metadata.
+function credentialPresence(server, env = process.env) {
+  const stat = fs.existsSync(credentialPath(env)) ? fs.statSync(credentialPath(env)) : null;
+  if (!stat) return { present: false, credentialRef: null };
+  const index = readStore('credential-state.json', env);
+  const metadata = index.metadata;
+  if (index.schemaVersion === 1 && metadata && metadata.mtimeMs === stat.mtimeMs &&
+      metadata.size === stat.size && metadata.ino === stat.ino && metadata.dev === stat.dev &&
+      index.records && typeof index.records === 'object' && !Array.isArray(index.records)) {
+    if (!Object.hasOwn(index.records, server)) return { present: false, credentialRef: null };
+    const entry = index.records[server];
+    if (entry?.present === true && typeof entry.credentialRef === 'string' &&
+        entry.credentialRef.startsWith('login:')) return entry;
+  }
+  return { present: true, credentialRef: 'login:pending' };
 }
 
 function saveCredential(server, credential, env = process.env) {
   const data = readAll(env);
   data[server] = credential;
   writeAll(data, env);
+  syncCredentialPresence(env);
 }
 
 function deleteCredential(server, env = process.env) {
@@ -70,6 +125,7 @@ function deleteCredential(server, env = process.env) {
   if (!Object.hasOwn(data, server)) return false;
   delete data[server];
   writeAll(data, env);
+  syncCredentialPresence(env);
   return true;
 }
 
@@ -105,5 +161,5 @@ async function withFileLock(env, task, { staleMs = 30000, waitMs = 15000 } = {})
 
 module.exports = {
   credentialPath, deleteCredential, readCredential, readStore, saveCredential, storePath, withFileLock,
-  writeStore
+  writeStore, credentialPresence, syncCredentialPresence
 };

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 = {