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

package/src/auth/credential-store.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { configDir } = require('./config');
+
+const fileName = 'credentials.json';
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function storePath(name, env) {
+  return path.join(configDir(env), name);
+}
+
+function credentialPath(env = process.env) {
+  return storePath(fileName, env);
+}
+
+function ensureDir(env) {
+  const dir = configDir(env);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+// Every config file is one JSON object keyed by oauth origin.
+function readStore(name, env = process.env) {
+  let text;
+  try {
+    text = fs.readFileSync(storePath(name, env), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+// Writes through a temporary file and rename so a crash never leaves half a file.
+function writeStore(name, data, env = process.env) {
+  const dir = ensureDir(env);
+  const target = storePath(name, env);
+  const temporary = path.join(dir, `.${name}.${process.pid}.${crypto.randomBytes(4).toString('hex')}`);
+  fs.writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, target);
+  fs.chmodSync(target, 0o600);
+}
+
+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 readCredential(server, env = process.env) {
+  const entry = readAll(env)[server];
+  return entry && typeof entry.accessToken === 'string' && typeof entry.refreshToken === 'string'
+    ? entry : null;
+}
+
+function saveCredential(server, credential, env = process.env) {
+  const data = readAll(env);
+  data[server] = credential;
+  writeAll(data, env);
+}
+
+function deleteCredential(server, env = process.env) {
+  const data = readAll(env);
+  if (!Object.hasOwn(data, server)) return false;
+  delete data[server];
+  writeAll(data, env);
+  return true;
+}
+
+// Serializes refresh across CLI processes. refresh_token rotates on every use, so two concurrent
+// refreshes would invalidate each other.
+async function withFileLock(env, task, { staleMs = 30000, waitMs = 15000 } = {}) {
+  const lock = path.join(ensureDir(env), `${fileName}.lock`);
+  const started = Date.now();
+  let handle;
+  for (;;) {
+    try {
+      handle = fs.openSync(lock, 'wx', 0o600);
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > staleMs) {
+          fs.rmSync(lock, { force: true });
+          continue;
+        }
+      } catch { continue; }
+      if (Date.now() - started > waitMs) throw new Error('Timed out waiting for the credential lock');
+      await sleep(100);
+    }
+  }
+  try {
+    return await task();
+  } finally {
+    fs.closeSync(handle);
+    fs.rmSync(lock, { force: true });
+  }
+}
+
+module.exports = {
+  credentialPath, deleteCredential, readCredential, readStore, saveCredential, storePath, withFileLock,
+  writeStore
+};

package/src/auth/oauth-client.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const { beginRequest } = require('../execution/request-state');
+
+class OAuthError extends Error {
+  constructor(message, { httpStatus, error } = {}) {
+    super(message);
+    this.httpStatus = httpStatus;
+    this.oauthError = error;
+  }
+}
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const errorCode = /^[a-z_]{1,64}$/;
+
+async function postForm(config, path, params) {
+  const body = new URLSearchParams({ client_id: config.clientId, ...params });
+  const encodedBody = body.toString();
+  const signal = AbortSignal.timeout(10000);
+  let response;
+  const finish = beginRequest();
+  try {
+    response = await fetch(`${config.oauthBaseUrl}${path}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+        accept: 'application/json'
+      },
+      body: encodedBody,
+      redirect: 'manual',
+      signal
+    });
+  } catch {
+    finish?.('unknown');
+    throw new OAuthError(`OAuth request to ${path} failed or timed out`);
+  }
+  let text;
+  try {
+    text = await response.text();
+    finish?.('sent');
+  } catch {
+    finish?.('unknown');
+    text = '';
+  }
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { json = null; }
+  if (!response.ok) {
+    // Only the RFC 6749 error code is surfaced; error_description may echo request values.
+    const error = typeof json?.error === 'string' && errorCode.test(json.error) ? json.error : undefined;
+    throw new OAuthError(
+      `OAuth ${path} returned HTTP ${response.status}${error ? ` ${error}` : ''}`,
+      { httpStatus: response.status, error });
+  }
+  return { httpStatus: response.status, json };
+}
+
+function tokenSet(json, now = Date.now()) {
+  if (!json || typeof json.access_token !== 'string' || !json.access_token ||
+      typeof json.refresh_token !== 'string' || !json.refresh_token) {
+    throw new OAuthError('OAuth token response is missing access_token or refresh_token');
+  }
+  const seconds = value => (Number.isSafeInteger(value) && value > 0 ? value : undefined);
+  const accessSeconds = seconds(json.expires_in);
+  const refreshSeconds = seconds(json.refresh_expires_in);
+  return {
+    accessToken: json.access_token,
+    refreshToken: json.refresh_token,
+    tokenType: typeof json.token_type === 'string' ? json.token_type : 'Bearer',
+    accessExpiresAt: accessSeconds ? now + accessSeconds * 1000 : undefined,
+    refreshExpiresAt: refreshSeconds ? now + refreshSeconds * 1000 : undefined
+  };
+}
+
+// The code stays valid for 60 seconds. oauth answers 503 temporarily_unavailable when another
+// login of the same user holds the lock, so retry within that window.
+async function exchangeCode(config, { code, verifier, redirectUri }, {
+  retryDelayMs = 2000, deadlineMs = 50000
+} = {}) {
+  const started = Date.now();
+  for (;;) {
+    try {
+      const { json } = await postForm(config, '/oauth/token', {
+        grant_type: 'authorization_code', code, code_verifier: verifier, redirect_uri: redirectUri
+      });
+      return tokenSet(json);
+    } catch (error) {
+      const retryable = error instanceof OAuthError && error.httpStatus === 503;
+      if (!retryable || Date.now() - started + retryDelayMs > deadlineMs) throw error;
+      await sleep(retryDelayMs);
+    }
+  }
+}
+
+async function refreshTokens(config, refreshToken) {
+  const { json } = await postForm(config, '/oauth/token', {
+    grant_type: 'refresh_token', refresh_token: refreshToken
+  });
+  return tokenSet(json);
+}
+
+async function revokeToken(config, token) {
+  await postForm(config, '/oauth/revoke', { token });
+}
+
+module.exports = { OAuthError, exchangeCode, refreshTokens, revokeToken, tokenSet };

package/src/auth/pkce.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+const base64url = buffer => buffer.toString('base64url');
+
+// 32 random bytes encode to a 43-character verifier, the RFC 7636 minimum length.
+function createVerifier() {
+  return base64url(crypto.randomBytes(32));
+}
+
+function challengeFor(verifier) {
+  return base64url(crypto.createHash('sha256').update(verifier, 'ascii').digest());
+}
+
+// 16 random bytes encode to a 22-character state.
+function createState() {
+  return base64url(crypto.randomBytes(16));
+}
+
+function createPkce() {
+  const verifier = createVerifier();
+  return Object.freeze({
+    verifier, challenge: challengeFor(verifier), method: 'S256', state: createState()
+  });
+}
+
+module.exports = { challengeFor, createPkce, createState, createVerifier };

package/src/auth/session.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const { oauthConfig } = require('./config');
+const { createPkce } = require('./pkce');
+const { detectTool } = require('./tool');
+const { startCallbackServer, defaultPort } = require('./callback-server');
+const { openBrowser } = require('./browser');
+const { OAuthError, exchangeCode, refreshTokens, revokeToken } = require('./oauth-client');
+const store = require('./credential-store');
+const { deleteContext } = require('../identity/context-store');
+
+const dayMs = 24 * 60 * 60 * 1000;
+
+class AuthRequiredError extends Error {}
+
+function loginUrl(config, { tool, redirectUri, pkce }) {
+  const url = new URL(config.loginPageUrl);
+  url.search = new URLSearchParams({
+    tool,
+    redirectUri,
+    codeChallenge: pkce.challenge,
+    codeChallengeMethod: pkce.method,
+    state: pkce.state
+  }).toString();
+  return url.toString();
+}
+
+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,
+    server,
+    clientId: credential.clientId,
+    tool: credential.tool,
+    loginAt: iso(credential.loginAt),
+    accessExpiresAt: iso(credential.accessExpiresAt),
+    refreshExpiresAt: iso(credential.refreshExpiresAt)
+  };
+}
+
+async function login({
+  env = process.env, browser = true, port = defaultPort, log = message => process.stderr.write(`${message}\n`),
+  open = openBrowser, timeoutMs
+} = {}) {
+  const config = oauthConfig(env);
+  const pkce = createPkce();
+  const tool = detectTool(env);
+  const server = await startCallbackServer({
+    state: pkce.state, port, timeoutMs, allowedOrigin: new URL(config.loginPageUrl).origin
+  });
+  const url = loginUrl(config, { tool, redirectUri: server.redirectUri, pkce });
+  let code;
+  try {
+    const opened = browser ? await open(url) : false;
+    log(opened ? '已在浏览器打开登录页。如未自动打开，请手动访问：' : '请在浏览器打开以下地址完成授权：');
+    log(url);
+    code = await server.waitForCode();
+  } finally {
+    await server.close();
+  }
+  let tokens;
+  try {
+    tokens = await exchangeCode(config, {
+      code, verifier: pkce.verifier, redirectUri: server.redirectUri
+    });
+  } catch (error) {
+    if (error instanceof OAuthError && error.httpStatus === 404) {
+      error.message += '。本次登录未完成，未保存新凭证。请先核对 CLI 版本、' +
+        'ZAN_SAAS_OAUTH_BASE_URL 和授权服务路由；浏览器授权完成不代表 CLI 已登录。';
+    }
+    throw error;
+  }
+  const credential = {
+    ...tokens, clientId: config.clientId, oauthBaseUrl: config.oauthBaseUrl, tool, loginAt: Date.now()
+  };
+  store.saveCredential(config.server, credential, env);
+  return summary(config.server, credential);
+}
+
+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 httpStatus;
+  try {
+    await revokeToken(config, credential.refreshToken);
+  } catch (error) {
+    httpStatus = error instanceof OAuthError ? error.httpStatus : undefined;
+    remoteRevocation = httpStatus === undefined ? 'unknown' : 'failed';
+  }
+  let localCredential = 'deleted';
+  try {
+    store.deleteCredential(config.server, env);
+  } catch {
+    localCredential = 'delete_failed';
+  }
+  if (remoteRevocation !== 'revoked' || localCredential !== 'deleted') {
+    const error = new Error(localCredential === 'deleted'
+      ? '本机个人凭证已清除，服务端会话撤销未确认；请核对授权服务状态。'
+      : '本机个人凭证清理失败；请按退出结果核对本地凭证与服务端会话。');
+    error.cliDetails = {
+      command: 'auth.logout', server: config.server, localCredential, remoteRevocation,
+      ...(httpStatus === undefined ? {} : { httpStatus })
+    };
+    throw error;
+  }
+  return { loggedOut: true, revoked: true, server: config.server };
+}
+
+function status({ env = process.env } = {}) {
+  const { server } = oauthConfig(env);
+  return summary(server, store.readCredential(server, env));
+}
+
+function interactive(env) {
+  return Boolean(process.stdin.isTTY && process.stderr.isTTY) && !env.CI &&
+    env.ZAN_SAAS_NO_BROWSER !== '1';
+}
+
+async function refreshIfNeeded(config, env, now) {
+  const key = config.server;
+  return store.withFileLock(env, async () => {
+    // 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);
+      return null;
+    }
+    let tokens;
+    try {
+      tokens = await refreshTokens(config, credential.refreshToken);
+    } catch (error) {
+      if (error instanceof OAuthError && error.oauthError === 'invalid_grant') {
+        store.deleteCredential(key, env);
+        return null;
+      }
+      // Keep using an access token that has not expired yet when refresh is unreachable.
+      if (credential.accessExpiresAt > now) return credential;
+      throw error;
+    }
+    const next = { ...credential, ...tokens };
+    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.
+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 config = oauthConfig(env);
+  let credential = store.readCredential(config.server, env);
+  if (credential && Number.isFinite(credential.accessExpiresAt) &&
+      credential.accessExpiresAt - now < dayMs) {
+    credential = await refreshIfNeeded(config, env, now);
+  }
+  if (!credential) {
+    if (!interactive(env)) {
+      throw new AuthRequiredError('未找到可用登录凭证，请先执行 `zan-saas auth login`；受控环境也可以配置 ZAN_SAAS_USER_ACCESS_TOKEN');
+    }
+    await loginImpl({ env });
+    credential = store.readCredential(config.server, env);
+    if (!credential) throw new AuthRequiredError('Login did not produce a credential');
+  }
+  return { token: credential.accessToken, source: 'login' };
+}
+
+module.exports = {
+  AuthRequiredError, login, loginUrl, logout, resolveAccessToken, status
+};

package/src/auth/tool.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const maxLength = 32;
+
+// Ordered by specificity; the first matching marker names the calling Agent tool.
+const markers = [
+  ['claude-code', env => env.CLAUDECODE === '1' || Boolean(env.CLAUDE_CODE_ENTRYPOINT)],
+  ['codex', env => Boolean(env.CODEX_SANDBOX || env.CODEX_MANAGED_BY_NPM || env.CODEX_HOME)],
+  ['gemini-cli', env => env.GEMINI_CLI === '1'],
+  ['cursor', env => Boolean(env.CURSOR_TRACE_ID || env.CURSOR_AGENT)],
+  ['opencode', env => Boolean(env.OPENCODE)]
+];
+
+function normalize(value) {
+  const text = String(value).trim().replace(/[^\w.-]+/g, '-').slice(0, maxLength);
+  return text || 'unknown';
+}
+
+function detectTool(env = process.env) {
+  if (env.ZAN_SAAS_TOOL) return normalize(env.ZAN_SAAS_TOOL);
+  const match = markers.find(([, test]) => test(env));
+  return match ? match[0] : 'unknown';
+}
+
+module.exports = { detectTool, maxLength };

package/src/cli/command-paths.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const { Command } = require('commander');
+const { validDomainName } = require('./domain-catalog');
+const { validateAt } = require('../execution/command-policy');
+const { riskLabels } = require('./help-text');
+
+const namePattern = /^[a-z][a-z0-9-]*$/;
+const taskPattern = /^\+[a-z][a-z0-9-]*$/;
+const risks = new Set(['read', 'low', 'medium', 'high']);
+const contracts = new WeakMap();
+const domains = new WeakMap();
+
+function group(parent, name) {
+  let command = parent.commands.find(entry => entry.name() === name);
+  if (!command) {
+    command = new Command(name).copyInheritedSettings(parent);
+    parent.addCommand(command);
+  }
+  if (command._actionHandler) throw new Error(`Command is already executable: ${name}`);
+  return command;
+}
+
+function registerDomain(program, definition) {
+  const { name, description, skill } = definition;
+  if (!validDomainName(name) || !description || skill !== `zan-saas-${name}`) {
+    throw new Error(`Invalid native domain: ${name}`);
+  }
+  const command = group(program, name);
+  if (domains.has(command) || command.commands.length) {
+    throw new Error(`Domain is already registered: ${name}`);
+  }
+  command.description(description);
+  command.allowExcessArguments(false)
+    .exitOverride()
+    .configureOutput({ writeErr: () => {} });
+  command.addHelpText('after', () =>
+    `${command.commands.some(child => child.name() !== 'help') ? '' :
+      '\n本领域尚未发布业务命令。\n'}` +
+    `\n领域指引：zan-saas skills read ${skill}`);
+  domains.set(command, { name, description, skill });
+}
+
+function publishedDomains(program) {
+  return program.commands.map(command => domains.get(command)).filter(Boolean);
+}
+
+function validateAvailability(availability = 'available') {
+  if (!['available', 'preview_only'].includes(availability)) {
+    throw new Error('Command availability must be available or preview_only');
+  }
+  return availability;
+}
+
+function addBusinessCommand(program, kind, domain, resource, command, risk, at, availability) {
+  const action = command.name();
+  const resources = Array.isArray(resource) ? resource : [resource];
+  const valid = namePattern.test(domain) &&
+    (kind === 'atomic'
+      ? resources.length > 0 && resources.every(value => typeof value === 'string' && namePattern.test(value)) &&
+        namePattern.test(action)
+      : kind === 'task' && resource === null && taskPattern.test(action));
+  if (!valid || !risks.has(risk) || !command._actionHandler) {
+    throw new Error(`Invalid ${kind} command path or risk: ${domain} ${resource || ''} ${action}`);
+  }
+  validateAt(at);
+  availability = validateAvailability(availability);
+  const domainGroup = group(program, domain);
+  const parent = kind === 'atomic' ? resources.reduce(group, domainGroup) : domainGroup;
+  if (parent.commands.some(entry => entry.name() === action)) {
+    throw new Error(`Command is already registered: ${domain} ${resource || ''} ${action}`);
+  }
+  const explicitExitCallback = command._exitCallback;
+  command.copyInheritedSettings(parent);
+  // Commander also copies the parent's exit callback; preserve a leaf's explicit policy.
+  if (explicitExitCallback) command.exitOverride(explicitExitCallback);
+  parent.addCommand(command);
+  const skill = domains.get(domainGroup)?.skill;
+  contracts.set(command, { kind, risk, skill, at, availability });
+  command.addHelpText('after', `\n风险：${riskLabels[risk]}${skill ? `\n领域指引：zan-saas skills read ${skill}` : ''}`);
+  return command;
+}
+
+function addAtomicCommand(program, domain, resource, command, risk, at, availability) {
+  return addBusinessCommand(program, 'atomic', domain, resource, command, risk, at, availability);
+}
+
+function addTaskCommand(program, domain, command, risk, at, availability) {
+  return addBusinessCommand(program, 'task', domain, null, command, risk, at, availability);
+}
+
+function commandPath(command) {
+  const parts = [];
+  for (let current = command; current.parent; current = current.parent) {
+    parts.unshift(current.name());
+  }
+  return parts.join('.');
+}
+
+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)) {
+    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)) {
+    return { kind: 'system', risk: 'low', availability: 'available' };
+  }
+  if (path === 'api') return { kind: 'raw-api', risk: 'unknown', availability: 'available' };
+  const parts = path.split('.');
+  const contract = contracts.get(command);
+  if (contract?.kind === 'atomic' &&
+      parts.length >= 3 && parts.every(part => namePattern.test(part))) return contract;
+  if (contract?.kind === 'task' &&
+      parts.length === 2 && namePattern.test(parts[0]) &&
+      taskPattern.test(parts[1])) return contract;
+  throw new Error(`Command has no valid published contract: ${path}`);
+}
+
+module.exports = {
+  registerDomain, publishedDomains, addAtomicCommand, addTaskCommand, commandContract, commandPath,
+  validateAvailability
+};

package/src/cli/context-help.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { Command, Help } = require('commander');
+const { commandContract, commandPath } = require('./command-paths');
+const { isAvailable } = require('../execution/command-policy');
+const { chineseHelp, positionLabels } = require('./help-text');
+const { parserFailure } = require('./parser-policy');
+
+const helpCommands = new WeakSet();
+const isContextHelp = command => helpCommands.has(command);
+
+function businessContract(command) {
+  if (!command._actionHandler || isContextHelp(command)) return null;
+  const contract = commandContract(commandPath(command), command);
+  return ['atomic', 'task'].includes(contract.kind) ? contract : null;
+}
+
+function configureContextHelp(program, state, loadDomain) {
+  function applicable(command) {
+    if (isContextHelp(command)) return true;
+    const contract = businessContract(command);
+    if (contract) return isAvailable(contract.at, state.context);
+    const children = command.commands.filter(child => !isContextHelp(child));
+    return !children.length || children.some(applicable);
+  }
+
+  function positions(command, result = new Set()) {
+    const contract = businessContract(command);
+    if (contract) result.add(contract.at);
+    for (const child of command.commands) positions(child, result);
+    return [...result].sort();
+  }
+
+  const helpConfiguration = {
+    ...chineseHelp,
+    visibleCommands(command) {
+      const all = Help.prototype.visibleCommands.call(this, command);
+      return state.status === 'ready' ? all.filter(applicable) : all;
+    },
+    subcommandDescription(command) {
+      const description = Help.prototype.subcommandDescription.call(this, command);
+      if (command.parent === program) return description;
+      const at = positions(command);
+      const labels = at.includes('all') ? positionLabels.all :
+        at.map(position => positionLabels[position]).join('、');
+      return labels ? `${description} [适用位置：${labels}]` : description;
+    }
+  };
+  program.configureHelp(helpConfiguration);
+  program.addHelpText('afterAll', ({ command }) => {
+    const contract = businessContract(command);
+    const declared = contract ? `适用位置：${positionLabels[contract.at]}\n` : '';
+    if (state.status !== 'ready') {
+      const status = state.status === 'missing'
+        ? '当前店铺：未设置，已列出全部已发布命令。\n' +
+          '设置店铺：zan-saas shop list，然后执行 zan-saas shop use <kdtId>。'
+        : '店铺上下文无效，已列出全部已发布命令。\n' +
+          '检查 ZAN_SAAS_CONTEXT 中的 userId、hq、shopId 和 orgType，或清除无效配置。';
+      return `\n${declared}${status}`;
+    }
+    const status = `当前位置：${positionLabels[state.context.orgType]}；实际权限由服务端校验。`;
+    if (contract) {
+      return `\n${declared}${status}\n${isAvailable(contract.at, state.context)
+        ? '此命令适用于当前位置。'
+        : `当前组织不可使用此命令，需要${positionLabels[contract.at]}上下文。`}`;
+    }
+    const children = command.commands.filter(child => !isContextHelp(child));
+    return `\n${status}${children.length && !children.some(applicable)
+      ? '\n当前位置没有适用的业务命令。' : ''}`;
+  });
+
+  function install(command = program) {
+    command.configureHelp(helpConfiguration).helpOption('-h, --help', '显示帮助');
+    if (command._actionHandler || isContextHelp(command)) return;
+    command.addHelpCommand(false);
+    if (!command.commands.some(child => isContextHelp(child))) {
+      const help = new Command('help').copyInheritedSettings(command)
+        .description('查看指定命令的帮助')
+        .argument('[path...]', '用空格或点分隔的子命令路径')
+        .allowExcessArguments(false)
+        .action(parts => {
+          let target = command;
+          for (const part of parts.flatMap(value => value.split('.'))) {
+            if (target === program) loadDomain(part);
+            const child = target.commands.find(child =>
+              child.name() === part || child.aliases().includes(part));
+            if (!child || isContextHelp(child)) {
+              throw parserFailure(target, 'unknown_command', { token: part });
+            }
+            target = child;
+          }
+          target.outputHelp();
+        });
+      helpCommands.add(help);
+      command.addCommand(help);
+    }
+    for (const child of command.commands) install(child);
+  }
+  return install;
+}
+
+module.exports = { configureContextHelp, isContextHelp };