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

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

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 3,
+  "domain": "valuecard",
+  "businessCommands": [
+    {
+      "path": "valuecard.card.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "valuecard/card/get/command.js",
+      "fingerprint": "d5819f697caf55a03a7a111abfa9c86764fb2597a536be9e5e5d705c1a91829e"
+    },
+    {
+      "path": "valuecard.card.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "valuecard/card/list/command.js",
+      "fingerprint": "d96d40fd6d68d96f62a809de403fe79274bb4ed671fd166eb6ecba22acd55179"
+    }
+  ]
+}

package/src/commands/native/valuecard/domain.json

@@ -0,0 +1,3 @@
+{
+  "description": "储值卡：余额卡与礼品卡的资产和余额"
+}

package/src/commands/native/valuecard/shared/projection.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { normalizeMoney } = require('../../../../execution/money');
+const { object } = require('../../../../execution/query-api');
+
+function parseInclude(value) {
+  if (value === undefined) return [];
+  const modules = value.split(',').map(entry => entry.trim());
+  if (modules.length !== 1 || modules[0] !== 'template') {
+    throw new TypeError('Invalid include selection');
+  }
+  return modules;
+}
+
+function projectCardType(value, source) {
+  if (!['template_type', 'card_sub_type'].includes(source)) {
+    throw new TypeError('Invalid card type source');
+  }
+  if (source === 'template_type' ? !Number.isSafeInteger(value) :
+    typeof value !== 'string' || !value.trim()) {
+    throw new TypeError('Invalid card type');
+  }
+  if (value === (source === 'template_type' ? 1001 : '1001')) return 'balance';
+  if (value === (source === 'template_type' ? 1002 : '1002')) return 'gift';
+  throw new RangeError('Unsupported card type');
+}
+
+function projectBalance(data) {
+  if (!object(data)) throw new TypeError('Invalid balance source');
+  const amounts = [data.denomination, data.principal_denomination, data.bonus_denomination];
+  if (!amounts.every(Number.isSafeInteger) ||
+      BigInt(amounts[0]) !== BigInt(amounts[1]) + BigInt(amounts[2])) {
+    throw new TypeError('Invalid balance amounts');
+  }
+  const money = { $comment: 'upstream-money:fen' };
+  return {
+    totalBalance: normalizeMoney(amounts[0], money),
+    principalBalance: normalizeMoney(amounts[1], money),
+    bonusBalance: normalizeMoney(amounts[2], money)
+  };
+}
+
+function projectTemplate(data) {
+  if (!object(data) || typeof data.template_no !== 'string' || !data.template_no.trim()) {
+    throw new TypeError('Invalid template number');
+  }
+  const template = { templateNo: data.template_no };
+  if (Object.hasOwn(data, 'template_name')) {
+    if (data.template_name !== null && typeof data.template_name !== 'string') {
+      throw new TypeError('Invalid template name');
+    }
+    template.templateName = data.template_name;
+  }
+  return template;
+}
+
+module.exports = { parseInclude, projectCardType, projectBalance, projectTemplate };

package/src/commands/system/api.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { Command } = require('commander');
+const { requestApi } = require('../../transport/api');
+const { withSystemSchema } = require('./contracts');
+
+async function sendRawApi(method, path, options) {
+  if (method !== 'POST') throw new Error('Only POST is supported by the referenced API protocol');
+  if (!options.yes) throw new Error('Raw API risk is unknown; review the target and pass --yes to send');
+  let body;
+  try {
+    body = JSON.parse(options.data);
+  } catch {
+    throw new Error('--data must be a JSON object');
+  }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw new Error('--data must be a JSON object');
+  }
+  const response = await requestApi({ path, body });
+  if (!response.ok) {
+    throw new Error(`API returned HTTP ${response.httpStatus}; request was sent but not confirmed successful`);
+  }
+  return { sent: true, httpStatus: response.httpStatus, body: response.body };
+}
+
+function createApiCommand() {
+  return withSystemSchema(new Command('api')
+    .description('按接口名和版本发送原始 POST 请求')
+    .argument('<method>', '请求方法，仅支持 POST')
+    .argument('<path>', '接口名和版本，格式为 <api-name>/<version>')
+    .option('--data <json>', 'JSON 对象请求体', '{}')
+    .option('--yes', '确认本次请求的未知副作用并发送')
+    .addHelpText('after', `
+目标可以是已登记或未登记的 API，不接收任意 URL。
+默认先使用 auth login 保存的个人凭证；受控环境配置 ZAN_SAAS_USER_ACCESS_TOKEN 时使用环境凭证。
+发送须 --yes，仅确认未知副作用，不证明服务端授权。
+退出0、HTTP 2xx 和 sent=true 只说明收到响应，不证明业务成功、异步完成或写入完成。
+body 是脱敏后的原始文本；即使 HTTP 200 正文含 success=false，也不按业务失败改变退出码。
+不提供 --dry-run、自动金额时间转换或自动重试；按目标 API 契约解释 body。
+`)
+    .action(async (method, path, options) => {
+      const result = await sendRawApi(method, path, options);
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+    }), 'api');
+}
+
+module.exports = { createApiCommand, sendRawApi };

package/src/commands/system/auth.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const { Command } = require('commander');
+const session = require('../../auth/session');
+const account = require('../../transport/account-api');
+const { readContext } = require('../../identity/context');
+const { contextInput } = require('../../identity/context-store');
+const { withSystemSchema } = require('./contracts');
+const { createPrinter, formatOption } = require('./printer');
+const { shopSelectionHint } = require('./shop-guidance');
+
+const pad = value => String(value).padStart(2, '0');
+
+// Local time without seconds, e.g. 2026-11-10 15:27.
+function localTime(iso) {
+  const date = new Date(iso);
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+const cloudAccountHint = '有赞云账号开通未确认，不影响本次个人登录。请先核对账号接口状态。';
+
+const text = {
+  login: value => {
+    const lines = [value.refreshExpiresAt
+      ? `登录成功，凭证有效期至 ${localTime(value.refreshExpiresAt)}。` : '登录成功。'];
+    if (value.cloudAccount?.ensured === false) lines.push(cloudAccountHint);
+    lines.push(value.shopId ? `当前店铺上下文：kdtId ${value.shopId}。` : '当前没有有效的店铺上下文。',
+      shopSelectionHint);
+    return lines.join('\n');
+  },
+  status: value => {
+    if (!value.loggedIn) return `未登录（${value.server}）。执行 zan-saas auth login 登录。`;
+    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('当前没有有效的店铺上下文。');
+    lines.push(shopSelectionHint);
+    return lines.join('\n');
+  },
+  logout: value => (value.revoked ? '已退出当前授权服务下的本机个人会话。' : '当前授权服务下未保存个人凭证，无需退出。'),
+  whoami: value => `当前用户：${value.nickName || '未设置昵称'}（userId ${value.userId}` +
+    `${value.mobile ? `，手机 ${value.mobile}` : ''}）`
+};
+const printer = createPrinter(text);
+
+function selectedShopId(env = process.env) {
+  const state = readContext(contextInput(env));
+  return state.status === 'ready' ? state.context.shopId : null;
+}
+
+// Opening the cloud account is best effort: login never fails because of it.
+async function loginWithAccount({ env = process.env, ...options } = {},
+  { login = session.login, ensureCloudUser = account.ensureCloudUser } = {}) {
+  const value = await login({ env, ...options });
+  let cloudAccount;
+  try {
+    await ensureCloudUser(env);
+    cloudAccount = { ensured: true };
+  } catch {
+    cloudAccount = { ensured: false };
+  }
+  return { ...value, shopId: selectedShopId(env), cloudAccount };
+}
+
+const defaults = {
+  login: options => loginWithAccount(options),
+  logout: options => session.logout(options),
+  status: options => ({ ...session.status(options), shopId: selectedShopId(options?.env) }),
+  whoami: () => account.whoami()
+};
+
+function createAuthCommand(impl = defaults) {
+  const auth = new Command('auth').description('登录、查看登录状态和退出登录');
+  withSystemSchema(auth.command('login')
+    .description('在浏览器中授权登录并保存个人凭证')
+    .option('--no-browser', '不自动打开浏览器；打印地址后仍等待手动授权')
+    .addOption(formatOption())
+    .addHelpText('after', `
+登录页回调到 http://127.0.0.1:<port>/callback，默认端口 38721，被占用时改用随机端口。
+默认使用生产授权服务，ZAN_SAAS_OAUTH_BASE_URL 可以覆盖。
+--no-browser 只跳过自动打开浏览器，仍等待授权回调并保存个人凭证，默认超时5分钟。
+人机交接：Agent 启动命令并把输出的登录地址交给用户；用户在浏览器确认后，Agent 等待本命令回调，再执行 zan-saas auth status 确认。用户取消或超时后重新执行本命令。
+登录成功后执行 zan-saas shop current 查看当前店铺。
+首次选店或需要切店时，先执行 zan-saas shop list，由用户选定 kdtId，再执行 zan-saas shop use <kdtId>。
+执行 zan-saas shop current 确认实际生效的店铺，再开始业务查询；切店无需重新登录。
+登录后尝试开通有赞云账号，未确认开通时不影响本次个人登录，应核对账号接口状态。
+浏览器授权完成后仍须成功换取并保存凭证；本命令失败时停止，不进入选店或业务查询。
+`)
+    .action(async options => {
+      printer('login', options.format)(await impl.login({ browser: options.browser }));
+    }), 'auth.login');
+  withSystemSchema(auth.command('logout')
+    .description('撤销当前授权服务下保存的个人会话，并清除本机凭证和已选店铺')
+    .addOption(formatOption())
+    .addHelpText('after', `
+仅处理当前授权服务下保存的个人凭证，不清除或撤销环境注入的 token。
+远端撤销失败或结果未知时仍尝试本地清理，失败结果分别说明两者状态。
+成功退出不证明环境覆盖凭证已失效，也不退出其他授权服务下的个人会话。
+`)
+    .action(async options => { printer('logout', options.format)(await impl.logout()); }), 'auth.logout');
+  withSystemSchema(auth.command('status')
+    .description('查看本机保存的凭证状态，不访问网络')
+    .addOption(formatOption())
+    .addHelpText('after', '\n只检查当前授权服务下的本机个人凭证，不检查环境覆盖凭证、服务端有效性或业务权限。\n')
+    .action(options => { printer('status', options.format)(impl.status()); }), 'auth.status');
+  withSystemSchema(auth.command('whoami')
+    .description('查看当前登录用户，无需选择店铺')
+    .addOption(formatOption())
+    .addHelpText('after', `
+调用账号接口网关，默认生产环境，ZAN_SAAS_ACCOUNT_API_BASE_URL 可以覆盖。手机号只显示前 3 位和后 4 位。
+`)
+    .action(async options => { printer('whoami', options.format)(await impl.whoami()); }), 'auth.whoami');
+  return auth;
+}
+
+module.exports = { createAuthCommand, localTime, loginWithAccount, selectedShopId, text };

package/src/commands/system/contracts.js

@@ -0,0 +1,373 @@
+'use strict';
+
+const { attachCommandSchema } = require('../../execution/command-schema');
+const { parserErrorModel } = require('../../execution/parser-error');
+
+function object(properties, required = Object.keys(properties)) {
+  return { type: 'object', additionalProperties: false, required, properties };
+}
+const text = { type: 'string' };
+const format = { type: 'string', enum: ['json', 'pretty'], description: '仅改变 JSON 缩进。' };
+const empty = object({});
+const error = object({
+  success: { const: false }, code: { const: -10001 }, message: text
+});
+const model = {
+  type: 'object', additionalProperties: true,
+  description: 'JSON Schema 模型，关键字与嵌套结构由各命令定义，引用解析使用同级 definitions。'
+};
+const command = object({
+  path: text, command: text, usage: text, description: text,
+  kind: { enum: ['system', 'raw-api', 'atomic', 'task'] },
+  risk: { enum: ['read', 'low', 'medium', 'high', 'unknown'] },
+  availability: { enum: ['available', 'preview_only'],
+    description: 'available 表示已开放执行；preview_only 表示仅支持离线预览。执行仍受登录、上下文和服务端权限限制。' },
+  skill: text, at: { enum: ['hq', 'shop', 'all'] },
+  arguments: { type: 'array', items: object({
+    name: text, description: text, required: { type: 'boolean' }, variadic: { type: 'boolean' }
+  }) },
+  options: { type: 'array', items: object({
+    flags: text, description: text, required: { type: 'boolean' },
+    default: true,
+    choices: { type: 'array', items: { anyOf: [
+      { type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'null' }
+    ] } }
+  }, ['flags', 'description', 'required']) },
+  schemaVersion: { const: 1 }, input: model, output: model, preview: model, error: model,
+  parserError: model,
+  definitions: { type: 'object', additionalProperties: { anyOf: [model, { type: 'boolean' }] } },
+  modules: { type: 'object', additionalProperties: object({
+    base: { type: 'boolean' }, description: text
+  }) },
+  success: { type: 'object', additionalProperties: true },
+  errors: { type: 'object', additionalProperties: true },
+  notes: { type: 'array', items: text }
+}, ['path', 'command', 'usage', 'description', 'kind', 'risk', 'availability', 'arguments', 'options',
+  'schemaVersion', 'input', 'output', 'parserError']);
+const domain = object({
+  path: text, description: text, kind: { const: 'domain' }, skill: text, parserError: model,
+  commands: { type: 'array', items: { $ref: '#/definitions/command' } }
+});
+const commandSummaryProperties = Object.fromEntries(
+  ['path', 'command', 'description', 'kind', 'risk', 'availability', 'skill', 'at']
+    .map(key => [key, command.properties[key]]));
+const commandSummaryRequired = ['path', 'command', 'description', 'kind', 'risk', 'availability'];
+const commandSummary = object(commandSummaryProperties, commandSummaryRequired);
+const domainSummary = object({
+  path: text, description: text, kind: { const: 'domain' }, skill: text
+});
+const summaryOutput = { oneOf: [
+  object({ ...commandSummaryProperties, summary: { const: true } },
+    [...commandSummaryRequired, 'summary']),
+  object({ ...domainSummary.properties, summary: { const: true },
+    commands: { type: 'array', items: commandSummary } }),
+  object({ summary: { const: true },
+    domains: { type: 'array', items: domainSummary },
+    commands: { type: 'array', items: commandSummary } })
+] };
+const sectionOutputs = ['input', 'output', 'preview', 'error'].map(section => object({
+  ...commandSummaryProperties, schemaVersion: { const: 1 }, section: { const: section },
+  [section]: model, definitions: command.properties.definitions, notes: command.properties.notes,
+  ...(section === 'error' ? { parserError: model } : {}),
+  ...(section === 'input' ? { usage: text, arguments: command.properties.arguments,
+    options: command.properties.options } : {}),
+  ...(['input', 'output'].includes(section) ? { modules: command.properties.modules } : {}),
+  ...(section === 'output' ? { success: command.properties.success } : {}),
+  ...(section === 'error' ? { errors: command.properties.errors } : {})
+}, [...commandSummaryRequired, 'schemaVersion', 'section', section,
+  ...(section === 'error' ? ['parserError'] : []),
+  ...(section === 'input' ? ['usage', 'arguments', 'options'] : [])]));
+const skill = object({
+  name: text, type: { enum: ['entry', 'shared', 'domain'] }, domain: text, description: text
+}, ['name', 'type', 'description']);
+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: '本机保存个人凭证且已知刷新有效期未到期；未知有效期时保留已有登录记录。不表示环境覆盖凭证或服务端权限有效。' },
+  server: serverField,
+  clientId: text, tool: text, loginAt: time, accessExpiresAt: time, refreshExpiresAt: time
+}, ['loggedIn', 'server']);
+const shopIdField = {
+  type: ['string', 'null'], description: '业务命令当前使用的店铺 ID；没有有效上下文时为 null。'
+};
+const statusOutput = object({ ...credentialStatus.properties, shopId: shopIdField },
+  [...credentialStatus.required, 'shopId']);
+const loginOutput = object({
+  ...statusOutput.properties,
+  cloudAccount: { oneOf: [
+    object({ ensured: { const: true } }),
+    object({ ensured: { const: false } })
+  ], description: '登录后尝试开通有赞云账号的结果；失败时 ensured 为 false，不影响登录。' }
+}, [...statusOutput.required, 'cloudAccount']);
+const id = { type: 'string', pattern: '^[1-9][0-9]*$' };
+const context = object({
+  userId: { type: 'string', minLength: 1 }, hq: id, shopId: id, orgType: { enum: ['hq', 'shop'] }
+});
+const nullableContext = { anyOf: [{ $ref: '#/definitions/context' }, { type: 'null' }] };
+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 contracts = {
+  install: {
+    input: object({
+      host: { type: 'string', description: '可省略；交互选择或检测的 Agent，显式多个名称用逗号分隔。' },
+      scope: { enum: ['user', 'project'], description: 'user 为个人目录，project 为当前项目；默认 user。' },
+      yes: { type: 'boolean', description: '使用显式宿主或检测结果，无交互提示。' },
+      directory: { type: 'string', description: '可选自定义 Skill 根目录，与 host 二选一。' },
+      package: { type: 'string', description: '可选本地 npm tgz，省略时持久安装本次运行的精确包版本。' },
+      dryRun: { type: 'boolean', description: '只显示计划，不下载或写入。' },
+      json: { type: 'boolean', description: '返回 JSON；否则返回面向人的安装结果文本。' }
+    }, ['scope']),
+    output: { oneOf: [
+      { type: 'string', description: '默认返回版本、宿主入口位置与使用提示。' },
+      object({
+        success: { const: true, description: 'CLI 及入口文件安装完成；不表示宿主已加载 Skill。' },
+        version: text, launcher: text, scope: { enum: ['user', 'project'] },
+        cliAction: { enum: ['reuse', 'install'] },
+        skillLoading: { const: 'not_verified', description: '尚未在宿主内验证 Skill 的发现及加载。' },
+        nextStep: { type: 'string', description: '在宿主中验证入口，或显式指定 Skill 目录的后续操作。' },
+        skills: { type: 'array', items: object({
+          host: text, path: text, action: { enum: ['unchanged', 'update', 'create'] }
+        }) }
+      }),
+      object({
+        success: { const: true, description: '安装计划检查通过；尚未执行安装。' },
+        cli: object({ action: { enum: ['reuse', 'install'] }, package: text }),
+        scope: { enum: ['user', 'project'] }, dryRun: { const: true },
+        skills: { type: 'array', items: object({
+          host: text, path: text, action: { enum: ['unchanged', 'update', 'create'] }
+        }) }
+      })
+    ] },
+    error: object({
+      ...error.properties,
+      details: object({
+        category: { const: 'installation', description: '安装子进程执行失败。' },
+        stage: { const: 'npm', description: '失败发生在 npm 子进程阶段。' },
+        operation: { enum: ['prefix', 'root', 'uninstall', 'install', 'other'], description: '失败的 npm 操作。' },
+        npmCode: { type: ['string', 'null'], description: '安全提取的 npm 或子进程错误码；未识别时为 null。' },
+        exitCode: { type: ['integer', 'null'], description: 'npm 子进程退出码；无法取得时为 null。' },
+        signal: { type: ['string', 'null'], description: '终止信号；未收到信号时为 null。' },
+        nextStep: { type: 'string', description: '按已识别原因给出的处理建议，不会自动清理或重试。' },
+        conflictPath: { type: 'string', description: '目录冲突时提取的脱敏源路径；其他情况省略。' },
+        destinationPath: { type: 'string', description: '目录冲突时提取的脱敏目标路径；其他情况省略。' }
+      }, ['category', 'stage', 'operation', 'npmCode', 'exitCode', 'signal', 'nextStep'])
+    }, ['success', 'code', 'message']),
+    notes: [
+      '安装器会持久安装本次 npm 包，并将轻量 Skill 写入明确选择或检测到的宿主目录。默认个人范围；非交互可用 --yes --host。',
+      'WorkBuddy 个人目录为 ~/.workbuddy/skills，CodeBuddy 为 ~/.codebuddy/skills；两者项目目录均为 .codebuddy/skills。',
+      '普通 npm 安装不执行安装器。dry-run 不下载或写入；同名外部命令、外部 Skill 或已修改入口保留并报错。',
+      '安装不执行登录、选店或业务请求；CLI 安装成功不证明宿主已加载 Skill 或业务权限有效。'
+    ]
+  },
+  schema: {
+    input: object({
+      path: { type: 'array', items: text, description: '可省略，使用空格或点分隔领域及命令路径。' },
+      summary: { type: 'boolean', description: '只返回轻量命令目录，不展开字段模型；不能与 section 同时使用。' },
+      section: { enum: ['input', 'output', 'preview', 'error'],
+        description: '指定完整叶子路径时，仅返回所选模型及引用闭包；input 同时保留 argv 参数、默认值和相关约束。' },
+      format
+    }, ['format']),
+    output: { oneOf: [
+      { $ref: '#/definitions/command' },
+      { $ref: '#/definitions/domain' },
+      object({
+        parserError: model,
+        domains: { type: 'array', items: { $ref: '#/definitions/domain' } },
+        commands: { type: 'array', items: { $ref: '#/definitions/command' } }
+      }),
+      summaryOutput,
+      ...sectionOutputs
+    ] },
+    definitions: { command, domain },
+    notes: [
+      '无路径返回完整目录，领域路径返回该领域及命令，叶子路径返回单条调用契约；未发布路径失败。',
+      '--summary 可用于根、领域或叶子路径；--section 仅用于叶子路径，未定义的模型返回错误，不生成空模型。两选项不能同时使用。',
+      '--section 保留 notes 和所需的递归 definitions；input 保留 arguments/options 与模块说明，output 保留成功说明，error 保留错误说明。',
+      '完整根、领域和叶子包含公共 parserError；error 分段同时保留它与原有 error。已有叶子的专用诊断及业务失败仍按 error 处理，summary 不展开错误模型。',
+      'input 是解析及必要上下文补全后的业务输入，不是 CLI 接收的 JSON；argv 的必填和默认值见 arguments/options。',
+      '不读取凭证、不联网、不按当前上下文删减契约，不证明员工权限或目标店铺开通。',
+      '字段模型可能共用同级 definitions；preview 描述实际 --dry-run 结果，不能作为真实执行的成功证据。'
+    ]
+  },
+  doctor: {
+    input: object({ format }),
+    output: object({
+      version: { type: 'string', description: '当前 CLI 包版本。' },
+      node: { type: 'string', description: '当前 Node.js 版本。' },
+      networkProbes: { const: false },
+      authentication: { const: 'not_checked', description: '本次离线诊断未检查认证，不表示已登录、未登录或凭证有效。' },
+      businessCommands: { type: 'integer', minimum: 0, description: '当前安装版登记的业务命令数。' }
+    }),
+    notes: ['离线读取本地安装摘要，不读取凭证、不联网；不证明认证、权限或真实接口可用。']
+  },
+  'auth.login': {
+    input: object({
+      browser: { type: 'boolean', description: '默认 true；--no-browser 仅跳过自动打开浏览器，仍打印地址、等待授权回调并保存个人凭证。' }
+    }),
+    output: loginOutput,
+    notes: [
+      '打开商家端 CLI 登录页，在 127.0.0.1 临时监听 /callback，拿到授权码后用 PKCE 换个人 token。',
+      'token 写入 ~/.zan-saas/credentials.json（权限 0600），按授权服务地址分开保存；输出不含 token。',
+      '用户取消或超时（5 分钟）时失败退出，不自动重试。',
+      '登录后用短超时尝试开通有赞云账号，未确认时只记录 ensured: false，不因此要求重新登录。',
+      '登录成功后用 shop current 查看当前店铺；首次选店或切换时用 shop list 查候选，按用户选择执行 shop use <kdtId>，再用 shop current 核对实际生效的上下文。',
+      '浏览器授权完成不代表本命令成功；换取凭证失败时未保存新凭证，停止后续选店和业务请求，按错误核查版本、配置及授权服务路由。'
+    ]
+  },
+  'auth.logout': {
+    input: empty,
+    output: object({
+      loggedOut: { const: true },
+      revoked: { type: 'boolean', description: '保存的个人会话已取得服务端撤销成功响应；本地没有凭证时为 false。不表示环境 token 或其他会话被撤销。' },
+      server: serverField
+    }),
+    error: object({
+      ...error.properties,
+      details: object({
+        command: { const: 'auth.logout' },
+        server: serverField,
+        localCredential: { enum: ['deleted', 'delete_failed'],
+          description: 'deleted 表示当前个人凭证已在本机清除或已不存在；delete_failed 表示本地清理未成功。' },
+        remoteRevocation: { enum: ['revoked', 'failed', 'unknown'],
+          description: 'revoked 已取得撤销成功响应；failed 撤销接口返回失败，不推断会话仍有效；unknown 请求或响应未能确认。' },
+        httpStatus: { type: 'integer', minimum: 100, maximum: 599,
+          description: '仅取得撤销接口失败 HTTP 响应时出现，不回显响应正文。' }
+      }, ['command', 'server', 'localCredential', 'remoteRevocation'])
+    }, ['success', 'code', 'message']),
+    notes: [
+      '只撤销当前授权服务下保存的个人会话，并清理本机凭证和当前已选店铺；不清除或撤销环境 token，不退出其他授权服务下的个人会话。',
+      '远端撤销失败或结果未知时仍尝试本地清理；失败退出且分别报告两者状态，不自动重试。',
+      '本地没有个人凭证时正常返回 revoked=false，不证明外部凭证或服务端其他会话已失效。'
+    ]
+  },
+  'auth.status': {
+    input: empty,
+    output: statusOutput,
+    notes: ['只读本地凭证文件，不联网，不证明 token 在服务端仍有效；按授权服务地址确定读取哪份凭证。']
+  },
+  'auth.whoami': {
+    input: empty,
+    output: object({
+      userId: { type: 'string', pattern: '^[1-9][0-9]*$', description: '有赞账号 ID，保留字符串。' },
+      nickName: { type: ['string', 'null'] },
+      mobile: { type: ['string', 'null'], description: '脱敏手机号，只保留前 3 位和后 4 位。' },
+      countryCode: { type: ['string', 'null'] }
+    }),
+    notes: [accountNote, '只输出这四个字段，不输出头像、性别等其他账号资料。']
+  },
+  'shop.list': {
+    input: object({
+      name: { type: 'string', minLength: 1, description: '店铺名称关键字，可省略。' },
+      pageNo: { type: 'integer', minimum: 1 },
+      pageSize: { type: 'integer', minimum: 1, maximum: 50 },
+      lineOfBusiness: { type: 'array', minItems: 1, items: { type: 'integer', minimum: 1 },
+        description: '业务线编码，默认微商城、教育、酒店、餐饮、美业、零售。' },
+      all: { type: 'boolean', description: '为 true 时不查询员工状态，显示全部店铺。' }
+    }, ['pageNo', 'pageSize']),
+    output: object({
+      total: { type: ['integer', 'null'], minimum: 0, description: '服务端在员工停用过滤前的匹配店铺总数；未提供有效总数时为 null，不以本页数量代替，也不是可用店铺总数。' },
+      totalScope: { const: 'before_staff_filter', description: 'total 不扣减员工已停用而隐藏的店铺；hidden 只统计当前页。' },
+      pageNum: { type: 'integer', minimum: 1 },
+      pageSize: { type: 'integer', minimum: 1 },
+      hasMore: { type: ['boolean', 'null'], description: '按过滤前总数与本页范围判断是否还有后续；总数未知时为 null，本页为空也不能据此判断取完。' },
+      nextPageNo: { type: ['integer', 'null'], minimum: 1, description: '有后续且页码可安全递增时给出下一页；否则为 null，不能单独据此判断取完。' },
+      windowLimitReached: { type: 'boolean', description: '页码达到 CLI 可安全表示的整数上限且尚未确认取完；应停止翻页。不是接口分页上限声明。' },
+      items: { type: 'array', items: object({
+        kdtId: id, shopName: { type: ['string', 'null'] },
+        shopRole: { type: ['integer', 'null'], description: '0 单店，1 总部，2 门店或网店，3 仓库，4 合伙人，5 第三方店铺，6 分销供货商店铺，7 前置仓。' },
+        orgType: { enum: ['hq', 'shop', null], description: '可选为上下文的组织类型；null 表示暂不能选择。' },
+        lifeCycleStatus: { anyOf: [{ type: 'string' }, { type: 'integer' }, { type: 'null' }] }
+      }) },
+      hidden: { type: 'integer', minimum: 0, description: '本页因员工账号已停用而隐藏的店铺数。' },
+      hiddenReason: { enum: ['staff_disabled', null], description: '本页有店铺因当前员工账号已停用而隐藏时为 staff_disabled，否则为 null。' },
+      nextStep: { type: ['string', 'null'], description: '有隐藏店铺时提示使用 --all；仅显示店铺，不增加业务权限。' },
+      unchecked: { type: 'array', items: id, description: '员工状态查询失败、未过滤而保留的店铺。' },
+      uncheckedReason: { type: ['string', 'null'], description: '第一个查询失败的原因；都成功时为 null。' }
+    }),
+    notes: [
+      accountNote, '结果按总部聚合，每项是总部或单店；只有 orgType 非 null 的店铺可以用 shop use 选择。',
+      '默认逐个查询当前用户在本页店铺的员工状态，隐藏已停用的店铺；total 仍是服务端总数，每页可能少于 pageSize。',
+      '按用户本次选择的 kdtId 执行 shop use <kdtId>，再用 shop current 核对；查询失败不表示账号没有店铺，账号路由错误不通过重复登录恢复。'
+    ]
+  },
+  'shop.use': {
+    input: object({ kdtId: id }),
+    output: object({
+      context: { $ref: '#/definitions/context' }, shopName: { type: ['string', 'null'] },
+      overriddenByEnv: { type: 'boolean', description: '为 true 时 ZAN_SAAS_CONTEXT 已设置，业务命令仍以它为准。' }
+    }),
+    definitions: { context },
+    notes: [
+      accountNote,
+      '先查询当前用户，再在其店铺列表中确认该店铺，只接受总部或单店；hq 与 shopId 都取该店铺 ID。',
+      '当前用户在该店铺的员工账号已停用时拒绝；员工状态查询失败不阻止选择。',
+      '上下文写入 ~/.zan-saas/context.json（权限 0600），不含凭证；本地上下文不是权限证明，服务端仍校验。',
+      '首次选择与切换店铺均使用本命令，无需重新登录；保存后用 shop current 确认实际店铺，overriddenByEnv 为 true 时不能声称当前上下文已切换。',
+      contextNote
+    ]
+  },
+  'shop.current': {
+    input: empty,
+    output: object({
+      source: { enum: ['env', 'saved', 'missing'] },
+      status: { enum: ['ready', 'invalid', 'missing'] },
+      context: nullableContext,
+      saved: { anyOf: [savedShop, { type: 'null' }] },
+      requestShopId: { type: ['string', 'null'], description: '环境变量 ZAN_SAAS_KDT_ID 的有效值；未设置或无效时为 null。不代表所有命令的最终请求店铺。' }
+    }),
+    definitions: { context },
+    notes: ['只读本地文件和环境变量，不联网。requestShopId 是环境变量值；部分命令按其目标店铺设置请求头，具体以命令契约为准。', contextNote]
+  },
+  'shop.clear': {
+    input: empty,
+    output: object({ cleared: { type: 'boolean', description: '本地有保存的店铺并已删除时为 true。' }, server: serverField }),
+    notes: ['只删除当前授权服务地址下保存的店铺，不联网，不影响 ZAN_SAAS_CONTEXT。']
+  },
+  'skills.list': {
+    input: empty,
+    output: object({ skills: { type: 'array', items: skill } }),
+    notes: ['返回当前安装版随包指引目录，不表示相应业务命令或员工权限全部具备。']
+  },
+  'skills.read': {
+    input: object({
+      skill: { type: 'string', minLength: 1, description: 'skills list 中的完整指引名称。' },
+      file: { type: 'string', minLength: 1, description: '已登记的相对 Markdown 路径，省略时读取 SKILL.md。' }
+    }, ['skill']),
+    output: { type: 'string', description: 'stdout 为原始 Markdown 文本，不是 JSON 字符串或 JSON 信封。' },
+    notes: [
+      '指引名称与文件路径分别传入，不放在同一对引号内；只能读取当前安装版登记的文件。',
+      '指引解释对象、选路和使用边界，不能新增可执行能力或授予权限。'
+    ]
+  },
+  api: {
+    input: object({
+      method: { const: 'POST' },
+      path: { type: 'string', pattern: '^/?[a-z][a-z0-9._-]*/[0-9]+\\.[0-9]+\\.[0-9]+$' },
+      data: { type: 'object', additionalProperties: true, description: '--data JSON 文本解析后的对象，省略选项时为空对象；不接受数组、null 或非对象。' },
+      yes: { const: true, description: '发送前须显式 --yes 确认未知副作用。' }
+    }),
+    output: object({
+      sent: { const: true }, httpStatus: { type: 'integer', minimum: 200, maximum: 299 },
+      body: { type: 'string', description: '脱敏后的原始响应文本，不自动解析 JSON，不判断业务成功。' }
+    }),
+    notes: [
+      '按明确的 API 名和版本发送 POST，可以是已登记或未登记的接口。风险未知，发送需 --yes；不继承领域命令的对象校验、风险分级和业务结果保证。',
+      '默认发送到生产开放 API 网关，ZAN_SAAS_API_BASE_URL 可覆盖；默认使用 auth login 保存的凭证，受控环境配置 ZAN_SAAS_USER_ACCESS_TOKEN 时使用环境凭证；不接受任意目标 URL。',
+      '退出0、HTTP 2xx 和 sent=true 只表示收到响应；即使正文报告业务失败也不改变退出码，不证明业务成功或写入完成。超时或断连时结果未知，不自动重试。',
+      '不提供 --dry-run，不自动应用业务金额或日期转换。'
+    ]
+  }
+};
+
+function withSystemSchema(command, name) {
+  const schema = { schemaVersion: 1, error, ...contracts[name] };
+  schema.error = { anyOf: [schema.error, structuredClone(parserErrorModel)] };
+  attachCommandSchema(command, schema);
+  return command;
+}
+
+module.exports = { withSystemSchema };

package/src/commands/system/doctor.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { Command, Option } = require('commander');
+const { version } = require('../../../package.json');
+const { withSystemSchema } = require('./contracts');
+
+function createDoctorCommand(businessCommandCount) {
+  return withSystemSchema(new Command('doctor')
+    .description('检查本地安装，不检查登录状态或网络')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .action(options => {
+      const result = {
+        version,
+        node: process.version,
+        networkProbes: false,
+        authentication: 'not_checked',
+        businessCommands: businessCommandCount
+      };
+      process.stdout.write(`${JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    }), 'doctor');
+}
+
+module.exports = { createDoctorCommand };