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

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 6,
-  "businessCommandCount": 59,
+  "businessCommandCount": 61,
   "domains": [
     {
       "name": "access",
@@ -10,7 +10,7 @@
       "indexFile": "access/commands.index.json",
       "commandCount": 2,
       "indexSize": 652,
-      "indexSha256": "77d7b2ec53cfff2a40f6dee4adb5501f12cf9681a09e7e759c78570feff46546"
+      "indexSha256": "0021c5c1d4c6d7fdab26a07e79554f35ee8240a0f8691392d0c2fad252f65334"
     },
     {
       "name": "aftersale",
@@ -50,7 +50,7 @@
       "indexFile": "customer/commands.index.json",
       "commandCount": 10,
       "indexSize": 3042,
-      "indexSha256": "f978a5016e0f30f32b4808d05f258992e1e162cff4c5448bd85672dc266a97b0"
+      "indexSha256": "3aa80cf1681c76e7d720f7f70c411850b53d8d312b5468124caa7cfa1a987652"
     },
     {
       "name": "fulfillment",
@@ -90,27 +90,27 @@
       "indexFile": "member/commands.index.json",
       "commandCount": 6,
       "indexSize": 1811,
-      "indexSha256": "62618e138aa9ef06743cfc9b3c1a08fd40883d7ebf8bc058e880f1b8a4a1bb65"
+      "indexSha256": "3f122369a09e91ac0d1ab8981bffef4d7a05ce99b8f4b0ae6cbd5b7588a9679c"
     },
     {
       "name": "order",
       "description": "订单：交易订单、商品行与售后履约摘要",
       "skill": "zan-saas-order",
-      "fingerprint": "ac980f08cb7f222d01d66b19562909115cf024ebd27e63b84d972006ac2f2c08",
+      "fingerprint": "6ecb777d56afd57f2bebd0a2ce76c8da81921d8b4e34635cde767a152efdb35b",
       "indexFile": "order/commands.index.json",
       "commandCount": 3,
       "indexSize": 918,
-      "indexSha256": "5b45860fd19977de29cb2d93772b0b3a0f3c9a52029b9bdd88191a9a39f9f3b5"
+      "indexSha256": "c179adeefb4b6dd8d14794bd5a5bd7aec7ac68001daf6221d06bd170f956388b"
     },
     {
       "name": "org",
       "description": "组织：组织资料、员工与角色关联",
       "skill": "zan-saas-org",
-      "fingerprint": "e2584b58e4c8ed6b2c080096e7e0fe1ba9c7f5297a1854d49f939749eef848c6",
+      "fingerprint": "9dd00cde0a08ee2f4632f4f3f89a29b8bc9fe9f962cf1c7a86ff1159ab352503",
       "indexFile": "org/commands.index.json",
       "commandCount": 4,
       "indexSize": 1185,
-      "indexSha256": "553820c277b0965b1a4e9d485290588e5939ca5a4b7986ea66501ceb5197f17f"
+      "indexSha256": "e0ecd80d3a8eb49cab3d0a940a69f26413a189c49fdbf46deca54387890ef581"
     },
     {
       "name": "points",
@@ -144,13 +144,13 @@
     },
     {
       "name": "valuecard",
-      "description": "储值卡：余额卡与礼品卡的资产和余额",
+      "description": "储值卡：余额卡与礼品卡的资产、余额、单页流水及有界精确查找",
       "skill": "zan-saas-valuecard",
-      "fingerprint": "3bc44b028d62afbce49cb0c9d8e08bbbcf8555e66c344909898ed3f6ac68551c",
+      "fingerprint": "f2e3dbd0efeb343ab32bfa3e290348e5b9ddbfa5f6aaa9ddbbf945b04cdfb96d",
       "indexFile": "valuecard/commands.index.json",
-      "commandCount": 2,
-      "indexSize": 652,
-      "indexSha256": "4f6bf3ad368eec7bd5f7bbcc160c848fb0bece49be8e9fa108e80eb52657005a"
+      "commandCount": 4,
+      "indexSize": 1256,
+      "indexSha256": "4bbce743893a7f62962874b73a7cf21c6a7427f805fd30b6332c587d3790a338"
     }
   ],
   "skills": [
@@ -165,7 +165,7 @@
         "SKILL.md",
         "references/host-entry.md"
       ],
-      "fingerprint": "6fd2bb9b078420651fc470a57b64a7a64e16e565ee5ca5f29445348a5a342031"
+      "fingerprint": "5b40c6bec46af43e31ea6406475c59afae705e9cc247640deafc4626b6c599b1"
     },
     {
       "name": "zan-saas-shared",
@@ -175,9 +175,11 @@
       "files": [
         "SKILL.md",
         "references/authentication.md",
+        "references/gateway-errors.md",
+        "references/shop-context.md",
         "references/value-processing.md"
       ],
-      "fingerprint": "5e4b2681b29e7e383fe0a39ca91327f7b9f00cded29c8f4da30eef8daca9dab0"
+      "fingerprint": "f9f150a5ff6aa79f574d96a783079ec3adf2bec720ed83d9610aea187edc4421"
     },
     {
       "name": "zan-saas-access",
@@ -338,11 +340,12 @@
       ],
       "files": [
         "SKILL.md",
+        "references/branch-counts.md",
         "references/order-get.md",
         "references/order-list.md",
         "references/order-scan.md"
       ],
-      "fingerprint": "5dc09b5addec07dfb12878d8047c53a8aee14dd0aaa6ad91f712d1b5b8f0829c"
+      "fingerprint": "69d818a88dfb42f41163b976d6883631a26d17420d02dd06c977d7443fedde86"
     },
     {
       "name": "zan-saas-org",
@@ -359,7 +362,7 @@
         "references/unit-get.md",
         "references/unit-list.md"
       ],
-      "fingerprint": "1ba9227cd426f9770a57c87fa335e5cac87f4c0e8d7d65f62437ab3bcbf1fa47"
+      "fingerprint": "769823815bbef49928da82b8f18d9379db2b6ca59230c5f8af2c1aad81559b5e"
     },
     {
       "name": "zan-saas-points",
@@ -409,16 +412,18 @@
       "name": "zan-saas-valuecard",
       "type": "domain",
       "domain": "valuecard",
-      "description": "储值卡：余额卡与礼品卡的资产和余额",
+      "description": "储值卡：余额卡与礼品卡的资产、余额、单页流水及有界精确查找",
       "dependsOn": [
         "zan-saas-shared"
       ],
       "files": [
         "SKILL.md",
         "references/card-get.md",
-        "references/card-list.md"
+        "references/card-list.md",
+        "references/transaction-list.md",
+        "references/transaction-scan.md"
       ],
-      "fingerprint": "8f170112f98379f817379bb2110bc3154a8651d8ea1e3e061ba4e0156b118152"
+      "fingerprint": "46c7896371f3ea67352159502a4424d6d36584cce93d6cedfa2a6fde372e22c7"
     }
   ]
 }

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.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@youzan-cloud/zan-saas-cli",
-      "version": "0.1.0-beta.4",
+      "version": "0.1.0-beta.8",
       "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.8",
   "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-order/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zan-saas-order
-description: 读取已知交易订单、按明确筛选查询一页订单或在显式创建或支付时间和预算内扫描时使用。区分交易明细、商品、支付事实和退款到账，不提供退款或发货操作。
+description: 读取交易订单、总部代查明确分店或有界分批统计分店订单数量时使用。区分交易明细、支付事实与退款到账，不提供退款或发货操作。
 ---
 
 # 订单 order
@@ -27,6 +27,7 @@ description: 读取已知交易订单、按明确筛选查询一页订单或在
 | --- | --- |
 | 已知订单号，核对订单状态、商品行及应付/实付 | `zan-saas order order get`；需要选择关联资料时读 [单笔订单](references/order-get.md)。 |
 | 按明确筛选读取一页交易订单 | `zan-saas order order list`；Agent 根据查看目标选择模块，不自动翻页。需要组合筛选或继续读取时读 [单页订单列表](references/order-list.md)。 |
+| 总部代查明确分店或统计多个分店订单数量 | 仍组合已有 `get/list/scan`，无跨店汇总命令。先按下节确定本批范围，再读 [分店分批计数](references/branch-counts.md)。 |
 | 在显式创建或支付时间和预算内跨页读取 | `zan-saas order order scan`，两轴二选一，返回订单与同轴停止位置，不承诺无遗漏。先读 [预算内订单扫描](references/order-scan.md)。 |
 | 同时查看订单可观察的售后、交付或其他有限资料 | 同一命令用 `--include` 追加所需模块，不追加关联请求。先读所选命令的 reference 与契约。 |
 | 查看已知订单收货资料的明文 | 详情仅支持显式选择字段；先读 [单笔订单](references/order-get.md) 和同版契约。当前员工字段授权及审计服务尚未接通，实际解密会停止，不能改用列表、导出或 Raw API 绕过。 |
@@ -35,6 +36,16 @@ description: 读取已知交易订单、按明确筛选查询一页订单或在
 
 缺少订单号或明确列表筛选时先向调用方取得定位信息，不自行遍历店铺。参数以叶子 help 和对应 schema 为准；发现到领域不等于具备所有订单操作。
 
+## 总部与分店范围
+
+省略 `--kdt-id` 使用当前 `context.shopId`；当前是总部时只查总部本身，不含分店。用户没指定其他范围时直接查询，并在回答中说明“只统计总部本身，不包含分店”，无需重复确认。用户明确指定分店时由 Agent 根据名称及同连锁目录定位，再在原总部上下文显式传入目标；这些订单读取不会保存新位置。非总部不能直接跨店，也不扩大详情解密权限。
+
+用户要求“所有门店”时先确定实体门店候选，不先用总部结果当连锁合计。每轮整个任务最多查询5家不同分店，默认串行；拆子调用、并行或自动开启下一批都不能绕过。目录发现使用 `org unit list`，每页最多50条、每轮最多2页，发现超过5家目标即可停止。筛选组2同时包含门店和网店，实体门店按返回角色2001选择，不将网店2002或总部混入；未读完或角色不明时说明范围未知。
+
+已明确本批不超过5家，直接执行，不再确认。只说“所有门店”时，只有相关目录已读完且目标不超过5家，才直接查这一小批；已发现超过5家则先展示候选，让用户选择本批最多5家或收窄范围，不自动取前5家。未读完且仅发现不超过5家也只展示已发现候选及覆盖限制，等待明确本批选择，不冒充全部门店数。名称到ID由Agent映射，不要求商家抄ID。
+
+只问数量时，每店用同一时间及状态筛选的 `order order list`，第一页、`--page-size 1`、不追加模块，只取可靠的 `data.pagination.total`。不扫描累加本页条数，不扩展金额。失败、总数缺失保持未知，只有明确返回0记零。报告本批小计、累计已查小计、已知剩余及未知范围；本批不自动进入下一批。后续等待用户明确继续或选择，保持同一截止时间和店铺去重状态。不同采集时点不声称共同快照；只有目标目录及所有批次完整覆盖且计数口径可相加时才给全范围合计。详见 [分店分批计数](references/branch-counts.md) 的停止、失败和记录规则。
+
 ## 范围与停止
 
 必须明确目标店铺并满足所选契约的同店约束，总部位置不自动授权读取分店。跨到履约域时重新核对目标命令的标识、上下文和支持范围，不能把订单查询成功当成关联查询授权。失败按同版错误停止，不遍历组织或自动换 token。

package/skills/zan-saas-order/references/branch-counts.md

@@ -0,0 +1,45 @@
+# 总部代查与分店分批计数
+
+用于明确分店目标、所有实体门店数量及用户选择下一批的场景。先遵守订单正文的5店、2页上限；它是Agent跨调用流程约束，不是CLI跨进程硬限流。没有 `order +summary` 或 `--scope stores`。
+
+## 固定本轮范围
+
+保留已核实的总部、操作者和环境，不改持久位置。记录用户原始目标、创建或支付时间轴、起止时间、状态等同一筛选；相对时间先转换为明确北京时间截止点。后续批次不把“现在”重新计算为更晚的截止点。
+
+目标由Agent从同连锁目录将名称映射到ID；同名或归属有歧义时提供可读名称及所属关系让用户选择。总部显式分店订单读取会自行验证总部、成员及分店基础绑定；不要将普通JSON或历史缓存当成员授权证明。无法核实的目标保持未知，不切店、不换身份或自动重试。
+
+## 发现与选择
+
+通过当前总部的 `org unit list --org-roles 2 --page-no 1 --page-size 50` 开始，仅在需要时读第二页，每轮最多2页。组2同时含门店及网店，按 `data.units[].orgRole` 的同版契约区分，实体门店为2001，网店为2002。不要把目录 `pagination.total` 当实体门店数量，也不要用短页或空页单独证明目录读完。以分页完整性、已返回角色及既定目标共同判断覆盖。
+
+- 明确选择了3家或5家本批门店，直接串行查询，不重复确认。必要定位仍计入本轮目录发现预算。
+- 用户仅要求所有门店，目录完整且仅1家或5家实体门店，可直接查询，保留目录完整性的依据。
+- 发现6家或50家实体门店，立即列出已发现候选，等待用户选最多5家。此时不发订单请求，不自动选前5家，不为列齐全部候选继续翻页。
+- 已读2页仍有后页，说明只是已发现候选，完整范围未知。即使只发现5家实体门店也不称全部，等待明确本批选择。
+- 返回角色不明、目录分页矛盾或无可靠覆盖依据，说明限制并停止受影响步骤，不推测实体门店数。
+
+总部自身与网店不自动加入实体门店统计。用户明确要包含这些范围时分别标明，只有各目标查询的范围及计数口径能相加时才合计，不将总部结果再加进分店小计造成重复。
+
+## 查询与本地汇总
+
+对本批去重后的目标逐店执行一条列表调用，例如：
+
+```sh
+zan-saas order order list --kdt-id <Agent映射的目标> --created-at "2026-11-01 00:00:00..2026-11-02 00:00:00" --page-no 1 --page-size 1
+```
+
+示例时间不是默认值。实际使用用户确认的时间和状态筛选。不要自动加 `--include items,payment,buyer`，不要逐单详情、扫描、解密或金额扩展。命令自身的成员分页核验是安全前置，不是Agent继续枚举候选的授权。
+
+检查退出码及同版输出，只把成功返回的非负安全整数 `data.pagination.total` 作为匹配数。本页数组长度、`returned`、未知总数和失败不是0。总数缺失时该店记“未知”，不得扫描补算。成功明确返回0时记“0”。
+
+保留每店的本轮记录，包括总部、目标ID及名称、筛选、采集时点、计数或未知原因、是否发出请求。同一筛选下每店仅计一次，不用下一批重复累加已查店铺；用户明确要求重新采集时替换该店观测，不叠加。
+
+单店失败保留该店未知及安全阶段信息，其他已知结果仍可报告。共同身份失效、总部核验失败等全局前置失败时停止剩余依赖调用，不逐店重复触发相同失败。无自动重试、自动下一批或凭证回退。
+
+## 输出及停止
+
+列出本批已查门店、每店已知值或未知原因、本批已知小计、累计已查小计、已知剩余和未知范围。全部失败时小计写“无可靠计数”，不写0；部分失败时明确小计仅含成功且有可靠总数的店铺。目录未完整时不提供完整门店总数；计数口径可加性未核实时只列各店值，不宣称连锁订单总量。
+
+本批结束立即停止，等待用户明确“继续”或选择下一批。已明确完整候选的剩余小批不超过5家时，“继续”可视为选择该剩余批；剩余超过5家或目录未知时仍先选择/收窄本批，不自动取前5家。保持原截止点与去重记录，不同采集时点不是共同服务端快照。
+
+只有目标目录完整、所有目标的各批全部有可靠计数、无重复目标且范围口径可相加，才给全范围合计。否则使用“本批已知小计”或“累计已查小计”，不能把缺店、失败店及未知店补零。

package/skills/zan-saas-order/references/order-get.md

@@ -1,5 +1,7 @@
 # 单笔交易订单的选择与结果边界
 
+总部普通读取可在原总部上下文显式指定同连锁分店，目录与基础绑定核验失败时不读取订单，也不保存位置。该能力不开放跨店解密；解密仍遵守既有同店、字段授权和审计限制。
+
 默认订单可含订单级支付时间 `paidAt` 和原始支付标记 `isPaid`，二者独立，不从状态、金额或彼此推算。缺失表示未取得，不补false，不回退创建时间。订单级支付时间不是首笔或最后一笔资金事件；整单 `realPayment` 也不是扣退款净额或商家到账。
 
 已知目标店铺和交易订单号、需要核对交易状态或成交商品时，选择 `zan-saas order order get`。缺少定位信息时先取得订单号，不自行搜索或遍历店铺。执行前读取叶子 help 和 `zan-saas schema order.order.get`，确认参数、默认计价币种、所需模块和授权前置；不要把默认计价口径当作逐订单币种或跨币种结算证明。

package/skills/zan-saas-order/references/order-list.md

@@ -1,5 +1,7 @@
 # 单页交易订单列表
 
+总部省略目标仍只查总部本身。明确分店时可在原总部上下文显式指定同连锁目标，命令先核实目录成员与分店绑定，不保存位置。多个分店数量使用 [分店分批计数](branch-counts.md)，不把一页条数或缺失总数当匹配总数。
+
 默认订单可含订单级支付时间 `paidAt` 和原始标记 `isPaid`，缺失表示未取得，false原样保留，不从状态或金额推算。列表 `payment` 不含详情 `realPayment`，不逐单补详情，不能用于求实付或扣退款净额；订单级支付时间不是逐笔资金事件。
 
 用户要按明确筛选浏览一页订单时，使用 `zan-saas order order list`。先读 `zan-saas schema order.order.list`，核对支持的筛选组合、时间轴、分页窗口及所需模块。

package/skills/zan-saas-order/references/order-scan.md

@@ -1,5 +1,7 @@
 # 预算内交易订单扫描
 
+总部显式分店扫描先核实总部、目录成员和分店基础绑定，所有前置共享请求及字节预算，查询不保存位置。前置尚未完成即耗尽预算时失败，不把空结果记为零。只统计多个分店数量应使用 [分店分批计数](branch-counts.md)，不要用扫描条数代替可靠总数。
+
 用户明确要求在创建或支付时间范围内跨页读取时，使用 `zan-saas order order scan`。先读 `zan-saas schema order.order.scan`，核对所选窗口、筛选、请求及结果预算。只查一页使用 `zan-saas order order list`，已知单号使用 `zan-saas order order get`。
 
 ## 范围与预算

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

@@ -17,6 +17,12 @@ description: 查询当前组织资料、总部下级组织、微商城单店员
 
 组织角色描述组织在体系中的身份，员工角色关联描述授角事实，角色定义目录描述有哪些角色，员工权限点描述本次可读权限。四者分别判断，角色名称不能推算权限或可授予性；业务线也不证明店铺类型。
 
+目录筛选组2同时含门店与网店，实体门店按返回角色2001选择，网店为2002；目录总数不是实体门店数。为“所有门店订单数量”发现候选时，每轮最多2页、每页最多50条，发现超过5家目标即停止并展示候选，未读完明确范围未知。订单查询批次、计数和失败汇总统一转交 `zan-saas skills read zan-saas-order`，本域不重复维护订单计算规则。
+
+商家在连锁内说的“店铺”通常指组织单元，先核对所属连锁和组织角色。账号层店铺入口由公共 `shop list` 发现，本域读取组织事实；当前位置由公共选店机制管理。需要内部切换、临时查询其他组织，或在分店浏览同连锁下级候选时，读取 `zan-saas skills read zan-saas-shared references/shop-context.md`。
+
+组织详情仍固定当前任务上下文；不能把下级 ID 直接代入原上下文的详情参数。准备其他组织的任务上下文后，所选叶子的产品、位置和权限限制仍适用。能够切到分店不扩大微商城单店员工入口的支持范围。
+
 ## 按目标选择命令
 
 | 用户目标 | 命令入口与读取条件 |

package/skills/zan-saas-org/references/unit-list.md

@@ -10,6 +10,8 @@
 
 根据返回的分页信息决定是否读取下一页。短页或空页不能单独证明全局无记录；跨页没有快照保证。继续读取须由用户目标决定，并限定页数或结果预算，不自动遍历。
 
+为订单分批统计发现候选时遵守订单域预算，每轮最多2页、每页最多50条；超过5家目标即可停止。筛选组2并非仅实体门店，返回2001为门店、2002为网店。目录未读完时只展示已发现候选，不宣称完整门店数；实际订单选择与计算转交订单域。
+
 部门关联只表示本次摘要返回的关系，不能据此构建完整部门树。网店营业、门店营业和门店状态独立表达，不能合成统一启停状态，也不能当作组织详情的运营状态。生命周期未返回不能推断永久有效。
 
 查询失败时保留原目标、筛选与扩展选择，先核查失败原因；不通过删除失败模块、换店或自动重试取得部分列表。本地预览不证明总部授权、员工权限或对象存在。

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

@@ -13,22 +13,37 @@ description: zan-saas 跨领域公共使用规则。首次调用或 CLI 版本
 
 网关返回 `4204` 时表示本次请求没有操作权限；应检查当前账号的店铺权限及店铺应用的接口开放能力授权。仅凭 `4204` 不能确定是哪一项缺失，可将错误中的接口、店铺和 `trace_id` 提供给管理员排查；不要自动申请授权或换店重试。
 
+业务错误诊断明确包含 `gatewayCode`，且遇到限流 `4101`、凭证 `4201/4202/4203`、客户标识 `4009` 或上游异常 `5001/5002` 时，读取 `zan-saas skills read zan-saas-shared references/gateway-errors.md`。按 `message`、`nextStep` 及已声明的 `recovery` 停止并排查，不自动重放。顶层同号 `businessCode` 不适用网关码指导；协议冲突、HTTP 鉴权拒绝及请求结果未知优先按实际诊断处理。
+
 需要登录时使用 `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` 发现，连锁下级候选按组织领域指引发现。
+
+| 用户意图 | 操作 |
+| --- | --- |
+| 切到另一家单店或连锁，之后默认使用它 | `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；未设置时使用 `zan-saas shop use <kdtId>` 保存的上下文，`zan-saas shop current` 可查看当前来源。`orgType` 只取 `hq` 或 `shop`；总部时 `shopId` 等于 `hq`，`shop` 时二者可以相同，单店按 `orgType: shop` 判断可用位置。员工、店铺与总部关系仍由服务端授权，不能把本地上下文当作权限证明。凭证不放进该 JSON。
+业务调用的用户上下文由入口注入，或通过 `ZAN_SAAS_CONTEXT` 提供仅含 `userId`、`hq`、`shopId`、`orgType` 的 JSON；否则取已初始化会话位置，无会话标识时取本机共享选择。`shop current` 查看实际来源。`hq` 表示租户根，单店为自身；`shopId` 表示当前组织；`orgType` 只取 `hq/shop`，后者为受支持的非总部位置，不能据此认定单店或分店角色。凭证不放进该 JSON，组织关系与权限仍由服务端核验。
 
 业务命令的 `at` 声明为 `hq`、`shop` 或 `all`。有有效上下文时，根与领域帮助按位置展示适用命令；无有效上下文时全量展示并提示未筛选。单条帮助始终可查，schema 始终保留完整契约。命令未展示时不自动切店或改用 Raw API；真实执行仍检查位置。
 
 ## 预览、请求与结果
 
+省略 `--kdt-id` 默认本次有效 `context.shopId`，总部默认只查总部本身，不包含分店。查询另一分店不等于保存新位置。支持总部显式目标的订单 `get/list/scan` 可在原总部上下文核验后读取；其他领域不可据此类推。需要临时上下文或切换时读取 [会话位置](references/shop-context.md)。跨店订单计数转订单域的分批规则，不自行遍历所有门店。
+
 `--help`、`schema`、`skills list/read` 和 `doctor` 是本地发现或诊断入口。`doctor` 不探测认证和远端业务，不以其成功报告店铺能力可用。
 
 本地指引读取因参数写法出错时，可以按帮助或错误提示修正后重新读取。例如 `skills read <skill> [file]` 的 Skill 名称和文件路径须分开传入，不能用同一对引号包住。该修正只用于本地读取，不授权重试业务请求。入口读取失败、指引未发布、文件不存在或版本无法确认时，说明缺口并停止，不猜路径或改用其他能力。
@@ -76,9 +91,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/gateway-errors.md

@@ -0,0 +1,29 @@
+# 业务网关错误排查
+
+仅当本次业务命令的安全诊断明确包含 `gatewayCode` 时，才按下表处理。顶层 `businessCode` 即使同号也不能套用，不从自由错误文本猜测码或根因。账号网关、OAuth 登录和续期错误按 [公共认证与会话](authentication.md) 排查，不套用本表。
+
+先停止本轮后续业务请求，保留原目标范围。只使用本版 `message`、`details.category/stage/requestState`、`nextStep` 及已声明的 `recovery`；旧诊断不一定提供 recovery。协议冲突、输入或上下文错误、叶子声明的响应原因优先。HTTP 明确为鉴权或权限拒绝时，不按矛盾的限流或上游异常码推断恢复；请求结果为 unknown 时不能认为未执行。不把失败或未知状态解释为空成功。
+
+| 网关码 | 下一步 |
+| --- | --- |
+| `4101` | 请求过于频繁或受限。停止本轮后续请求，核对频率、并发与可用配额。降低频率后由调用方重新决定是否发起；没有固定等待时长、恢复时间或配额承诺。持续出现时提交实际保留的安全诊断。 |
+| `4201` | 请求凭证无效。先区分凭证来源与目标店铺、应用授权范围，核对凭证值和授权。不能仅凭此码断定密码、员工权限或某一项授权失效。 |
+| `4202` | 请求凭证过期。个人登录按公共认证流程重新登录授权；显式环境身份由凭证提供方更新。不要自动切换来源或在业务失败后刷新并重放。 |
+| `4203` | 请求凭证不存在。按当前来源补齐有效认证并核查受控配置。不要在聊天中索取或提交 token。 |
+| `4204` | 同时核查当前账号的店铺权限和店铺应用的接口开放能力授权；持续拒绝时由管理员核查服务端限制。错误码不能单独确定根因，不自动申请授权、换身份或切店。 |
+| `4009` | 客户 open_id 无法解析。核对本命令契约中的客户标识、标识类型和目标店铺；只有 help/schema 实际暴露 `--yz-open-id` 时才使用该选项。它不是登录凭证问题，也不能证明客户在所有店铺均不存在。 |
+| `5001` / `5002` | 上游系统或业务异常，本次失败。先核对同版参数契约；参数符合且持续失败时提交安全接口、错误码和实际取得的追踪号。不要承诺稍后一定成功或修改某个参数必然修复。 |
+
+`4008`、`4010`、`5003` 和未知码仍按本次通用诊断处理。这里没有新增错误码查询命令或自动恢复机制。
+
+## 核对凭证来源
+
+普通使用优先采用 `zan-saas auth login` 保存的个人登录；没有个人登录记录时才使用 `ZAN_SAAS_USER_ACCESS_TOKEN`，受控环境显式要求环境身份时配置 `ZAN_SAAS_AUTH_SOURCE=env`。环境 token 不覆盖已有个人登录，个人登录失败也不自动回退到环境身份。不要为了绕过本次拒绝更改凭证来源。
+
+`zan-saas auth status --format json` 仅查看本地保存状态，不能验证环境 token 有效性、目标店铺匹配或业务权限。需要重新登录时，先读 `zan-saas auth login --help` 或 `zan-saas schema auth.login`，再按公共授权流程执行；环境身份由提供方更新配置。个人会话与开放平台应用 access_token 不作相同有效期承诺，不把固定七天或刷新后一小时当成本 CLI 会话规则。
+
+## 保留安全诊断后停止
+
+用 `zan-saas schema <完整命令路径>` 或该命令 `--help` 核对同版输入与错误契约。提交诊断中实际保留的 `api`、`gatewayCode`、`businessCode`、HTTP 状态和经过校验的 `trace_id/request_id`；没有追踪号时不补造。不要提交 token、Authorization、请求 body、客户标识、私人数据或自由上游消息。
+
+以上都是下一步指导，不自动登录、刷新、初始化应用、换店、换身份或等待重试，不自动重放。预请求正常续期仍由公共认证处理，同一命令的身份从首次实际请求开始冻结。重新认证或修正配置成功不代表原业务请求已经重试或成功；是否重新发起由调用方结合原请求状态明确决定。

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: zan-saas-valuecard
-description: 储值卡领域指引。查询余额卡、礼品卡的资产状态和本金、赠送金余额时使用；不与会员权益卡、积分或成长值混用。
+description: 储值卡领域指引。查询余额卡、礼品卡的资产状态、本金和赠送金余额，浏览一页储值流水或按原始标识跨页精确查找时使用；不与会员权益卡、积分或成长值混用。
 ---
 
 # 储值卡 valuecard
@@ -13,6 +13,8 @@ description: 储值卡领域指引。查询余额卡、礼品卡的资产状态
 
 系统卡号、卡面号、兑换码、模板号和客户标识不能互换。本金和赠送金是卡余额的组成，不等于冻结、可退金额或客户资产汇总；卡状态不能单独证明某订单可以支付。
 
+资源 `transaction` 表达店铺范围内按业务类型和业务时间读取的储值交易记录，不是当前卡资产、客户档案、充值单、支付单或退款单。流水记载的 `billCardNo` 不保证等于资产的 `cardNo`，不能拿它直接调用单卡查询；手机号不等于客户 `yzOpenId`，不通过当前持卡或手机号推断历史身份。流水交易单号 `tradeNo` 与外部支付请求号 `externalRequestNo` 分开。记录金额不代表统一余额增量，记录余额也不保证是交易前或交易后余额。
+
 例如，假设客户甲在同一模板下有两张卡，应保留两个实例及各自余额，不能按模板合并，也不能把其中一页相加后宣称客户总余额。
 
 权益卡的定义、持有与发放转交 `zan-saas skills read zan-saas-benefit`；客户档案转交 `zan-saas skills read zan-saas-customer`。储值资产不代替会员身份、积分或成长值。
@@ -23,10 +25,14 @@ description: 储值卡领域指引。查询余额卡、礼品卡的资产状态
 | --- | --- |
 | 已知完整系统卡号，查看这一张卡的状态和余额 | `zan-saas valuecard card get`；需要判断卡号、模板关联或未找到结果时读 [单卡查询](references/card-get.md)。 |
 | 已知客户，查看选定状态下的一页持卡 | `zan-saas valuecard card list`；需要判断状态覆盖、空页或能否继续读取时读 [客户持卡范围](references/card-list.md)。 |
+| 已知店铺、单个业务类型和业务发生时间，查看一页储值流水 | `zan-saas valuecard transaction list`；需要解释记录金额、关联单号或分页范围时读 [流水查询边界](references/transaction-list.md)。 |
+| 已知流水原始手机号、流水卡号、流水号或交易单号，按一种类型和时间跨页查找 | `zan-saas valuecard transaction scan`；先读 [有界流水查找](references/transaction-scan.md)，不使用系统卡号或客户 ID 猜匹配条件。 |
 
 只知道卡号时选择单卡，不猜客户；只知道客户时选择列表，不枚举卡号。还需要模板关联时按所选契约追加模块，关联存在不证明模板可售或适用某笔订单。
 
-制卡、充值、调账、退款、余额汇总、交易流水及完整模板查询尚无入口，需要这些能力时说明缺口并停止。
+流水 `list` 只浏览一页，`scan` 根据流水原始标识在有限范围内匹配；两者都不能证明某客户的完整交易历史。用户要查看某张卡当前余额时仍选单卡查询，不能用流水记录余额代替。
+
+制卡、执行充值、调账或退款、余额汇总、自动余额对账及完整模板查询尚无入口，需要这些能力时说明缺口并停止。按充值或退款业务类型读流水，不代表执行充值或退款，也不证明关联单据的处理状态。
 
 ## 选定入口后