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

package/src/commands/system/install.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const { Command, Option } = require('commander');
+const { withSystemSchema } = require('./contracts');
+const { install } = require('../../installation/install');
+
+function createInstallCommand() {
+  return withSystemSchema(new Command('install')
+    .description('安装 CLI 与 Agent 入口 Skill')
+    .option('--host <names>', '指定 Agent，多个用逗号分隔：workbuddy、codebuddy、codex、claude-code、cursor、trae')
+    .addOption(new Option('--scope <scope>', '安装范围，默认个人目录').choices(['user', 'project']).default('user'))
+    .option('-y, --yes', '非交互安装；未指定 host 时使用检测到的 Agent')
+    .option('--directory <dir>', '其他宿主的 Skill 目录，与 host 二选一')
+    .option('--package <file>', '本地验收使用的 npm .tgz 文件，依赖仍可能联网下载')
+    .option('--dry-run', '只显示安装计划，不下载或写入')
+    .option('--json', '输出 JSON 安装结果')
+    .addHelpText('after', `
+默认检测并选择 Agent，持久安装同版 CLI，再安装轻量入口。
+WorkBuddy、CodeBuddy、Codex、Claude Code、Cursor、Trae（中国版）支持个人与项目目录。
+WorkBuddy 个人目录为 ~/.workbuddy/skills，CodeBuddy 为 ~/.codebuddy/skills；两者项目目录均为 .codebuddy/skills。
+现有本项目开发链接可自动迁移；同名其他命令或已修改的 Skill 保留并报错。
+安装不执行登录、选店或业务查询。普通 npm 安装也不会自动修改宿主配置。
+
+示例：
+  npx @youzan-cloud/zan-saas-cli@latest install
+  zan-saas install --yes --host workbuddy
+  zan-saas install --yes --host codex,claude-code --scope project
+`)
+    .action(async options => {
+      const result = await install(options);
+      if (options.json || options.dryRun) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      else {
+        process.stdout.write(`安装完成：zan-saas ${result.version}\n`);
+        for (const skill of result.skills) process.stdout.write(`  ${skill.host}：${skill.path}\n`);
+        process.stdout.write('入口文件已就绪，尚未验证 Agent 是否加载。\n');
+        process.stdout.write(`${result.nextStep}\n`);
+      }
+    }), 'install');
+}
+
+module.exports = { createInstallCommand };

package/src/commands/system/printer.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { Option } = require('commander');
+
+// Terminals get a short sentence; pipes and agents keep the JSON contract. `extra` only feeds the text.
+function createPrinter(text) {
+  return (kind, format) => (value, extra) => {
+    const human = (format || (process.stdout.isTTY ? 'text' : 'json')) === 'text';
+    process.stdout.write(`${human ? text[kind](value, extra) : JSON.stringify(value)}\n`);
+  };
+}
+
+const formatOption = () => new Option('--format <format>', 'text 或 json，终端默认 text，管道默认 json')
+  .choices(['text', 'json']);
+
+module.exports = { createPrinter, formatOption };

package/src/commands/system/schema.js

@@ -0,0 +1,162 @@
+'use strict';
+
+const { Command, Option } = require('commander');
+const { commandContract, publishedDomains } = require('../../cli/command-paths');
+const { commandSchema } = require('../../execution/command-schema');
+const { publicCommandSchema } = require('../../execution/public-schema');
+const { isContextHelp } = require('../../cli/context-help');
+const { withSystemSchema } = require('./contracts');
+const { parserErrorModel } = require('../../execution/parser-error');
+
+function visibleCommands(program) {
+  const commands = [];
+  function visit(parent, path = []) {
+    for (const command of parent.commands) {
+      if (isContextHelp(command)) continue;
+      const parts = [...path, command.name()];
+      if (command.commands.length) visit(command, parts);
+      if (command._actionHandler) {
+        const key = parts.join('.');
+        commandContract(key, command);
+        commands.push({ path: key, command });
+      }
+    }
+  }
+  visit(program);
+  return commands;
+}
+
+function describeCommand(path, command) {
+  const { kind, risk, skill, at, availability } = commandContract(path, command);
+  return {
+    path,
+    command: `zan-saas ${path.replaceAll('.', ' ')}`,
+    usage: `zan-saas ${path.replaceAll('.', ' ')} ${command.usage()}`.trim(),
+    description: command.description(),
+    kind,
+    risk,
+    availability,
+    ...(skill ? { skill } : {}),
+    ...(at ? { at } : {}),
+    arguments: command.registeredArguments.map(argument => ({
+      name: argument.name(),
+      description: argument.description,
+      required: argument.required,
+      variadic: argument.variadic
+    })),
+    options: command.options.map(option => ({
+      flags: option.flags,
+      description: option.description,
+      required: option.mandatory,
+      ...(option.defaultValue !== undefined ? { default: option.defaultValue } : {}),
+      ...(option.argChoices ? { choices: option.argChoices } : {})
+    })),
+    ...publicCommandSchema(commandSchema(command)),
+    parserError: structuredClone(parserErrorModel)
+  };
+}
+
+function describeDomain(domain, commands) {
+  return {
+    path: domain.name,
+    description: domain.description,
+    kind: 'domain',
+    skill: domain.skill,
+    parserError: structuredClone(parserErrorModel),
+    commands: commands.filter(entry => entry.path.startsWith(`${domain.name}.`))
+      .map(entry => describeCommand(entry.path, entry.command))
+  };
+}
+
+function summarizeCommand(contract) {
+  return Object.fromEntries(['path', 'command', 'description', 'kind', 'risk', 'availability', 'skill', 'at']
+    .filter(key => Object.hasOwn(contract, key)).map(key => [key, contract[key]]));
+}
+
+function summarize(result) {
+  if (result.kind === 'domain') {
+    const { parserError, ...domain } = result;
+    return { ...domain, summary: true, commands: result.commands.map(summarizeCommand) };
+  }
+  if (result.path) return { ...summarizeCommand(result), summary: true };
+  return { summary: true,
+    domains: result.domains.map(({ commands, parserError, ...domain }) => domain),
+    commands: result.commands.map(summarizeCommand) };
+}
+
+// Keep complete referenced definitions, including transitive and cyclic references. Filtering only
+// the selected model without this closure would leave a valid-looking but unusable contract.
+function referencedDefinitions(value, definitions = {}) {
+  const selected = {};
+  const visit = node => {
+    if (!node || typeof node !== 'object') return;
+    if (typeof node.$ref === 'string' && node.$ref.startsWith('#/definitions/')) {
+      const name = node.$ref.slice('#/definitions/'.length).split('/')[0]
+        .replaceAll('~1', '/').replaceAll('~0', '~');
+      if (!Object.hasOwn(selected, name)) {
+        if (!Object.hasOwn(definitions, name)) throw new Error(`Missing schema definition: ${name}`);
+        Object.defineProperty(selected, name, { value: definitions[name], enumerable: true });
+        visit(definitions[name]);
+      }
+    }
+    for (const child of Object.values(node)) visit(child);
+  };
+  visit(value);
+  return selected;
+}
+
+function selectSection(contract, section) {
+  if (!Object.hasOwn(contract, section)) {
+    throw new Error(`Command ${contract.path} has no ${section} model`);
+  }
+  const result = { ...summarizeCommand(contract), schemaVersion: contract.schemaVersion,
+    section, [section]: contract[section] };
+  if (section === 'input') Object.assign(result, {
+    usage: contract.usage, arguments: contract.arguments, options: contract.options
+  });
+  if (contract.notes) result.notes = contract.notes;
+  if (['input', 'output'].includes(section) && contract.modules) result.modules = contract.modules;
+  if (section === 'output' && contract.success) result.success = contract.success;
+  if (section === 'error' && contract.errors) result.errors = contract.errors;
+  if (section === 'error') result.parserError = structuredClone(parserErrorModel);
+  const definitions = referencedDefinitions(result, contract.definitions);
+  if (Object.keys(definitions).length) result.definitions = definitions;
+  return result;
+}
+
+function createSchemaCommand(getProgram, preparePath = () => {}) {
+  return withSystemSchema(new Command('schema')
+    .description('查看命令的参数、输出与约束')
+    .argument('[path...]', '命令路径，使用空格或点分隔')
+    .option('--summary', '只列命令、描述、适用位置、风险和 Skill，不展开字段模型')
+    .option('--section <section>', '仅查看叶子命令的 input、output、preview 或 error 及所需引用定义')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .action((path, options) => {
+      if (options.summary && options.section) throw new Error('--summary 与 --section 不能同时使用');
+      if (options.section && !['input', 'output', 'preview', 'error'].includes(options.section)) {
+        throw new Error('--section 必须是 input、output、preview 或 error');
+      }
+      const key = (path || []).join('.').replaceAll(' ', '.');
+      preparePath(key);
+      const commands = visibleCommands(getProgram());
+      const found = commands.find(entry => entry.path === key);
+      const domains = publishedDomains(getProgram());
+      const domain = domains.find(entry => entry.name === key);
+      if (key && !found && !domain) throw new Error(`Command not published: ${key}`);
+      if (options.section && !found) throw new Error('--section 需要指定完整叶子命令路径');
+      let result = found
+        ? describeCommand(found.path, found.command)
+        : domain ? describeDomain(domain, commands)
+        : {
+          parserError: structuredClone(parserErrorModel),
+          domains: domains.map(entry => describeDomain(entry, commands)),
+          commands: commands.map(entry => describeCommand(entry.path, entry.command))
+        };
+      if (options.summary) result = summarize(result);
+      if (options.section) result = selectSection(result, options.section);
+      process.stdout.write(`${JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    }), 'schema');
+}
+
+module.exports = { createSchemaCommand, visibleCommands, describeCommand, referencedDefinitions, selectSection };

package/src/commands/system/shop-guidance.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const shopSelectionHint = [
+  '查看可选店铺：zan-saas shop list',
+  '选择或切换店铺：zan-saas shop use <kdtId>，将 <kdtId> 替换为目标店铺 ID。',
+  '确认当前店铺：zan-saas shop current'
+].join('\n');
+
+module.exports = { shopSelectionHint };

package/src/commands/system/shop.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const { Command, InvalidArgumentError } = require('commander');
+const account = require('../../transport/account-api');
+const { oauthConfig } = require('../../auth/config');
+const { readContext } = require('../../identity/context');
+const {
+  contextInput, deleteContext, readSavedContext, saveContext
+} = require('../../identity/context-store');
+const { withSystemSchema } = require('./contracts');
+const { createPrinter, formatOption } = require('./printer');
+const { shopSelectionHint } = require('./shop-guidance');
+
+const idPattern = /^[1-9]\d*$/;
+const orgLabels = { hq: '总部', shop: '单店' };
+const roleLabel = role => account.shopRoles[role] || '未知类型';
+const envNote = '环境变量 ZAN_SAAS_CONTEXT 已设置，业务命令仍以它为准。';
+
+function positiveInteger(name, max = Number.MAX_SAFE_INTEGER) {
+  return value => {
+    if (!idPattern.test(value) || Number(value) > max) {
+      throw new InvalidArgumentError(`${name} 必须是 1 到 ${max} 之间的整数。`);
+    }
+    return Number(value);
+  };
+}
+
+function lineOfBusinesses(value) {
+  const codes = value.split(',').map(code => code.trim());
+  if (!codes.every(code => idPattern.test(code) && Number.isSafeInteger(Number(code)))) {
+    throw new InvalidArgumentError('--line-of-business 必须是逗号分隔的正整数业务线编码。');
+  }
+  return codes.map(Number);
+}
+
+function shopIdOf(env) {
+  const state = readContext(contextInput(env));
+  return state.status === 'ready' ? state.context.shopId : null;
+}
+
+function requestShopIdOf(env) {
+  const value = env.ZAN_SAAS_KDT_ID;
+  return typeof value === 'string' && idPattern.test(value) && Number.isSafeInteger(Number(value))
+    ? value : null;
+}
+
+// Checks a few shops at a time; a failed check keeps the shop rather than hiding it by mistake.
+async function checkStaffStatuses(items, env, concurrency = 5) {
+  const checks = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      try {
+        checks[index] = { status: await account.staffStatus(items[index].kdtId, env) };
+      } catch (error) {
+        checks[index] = { error };
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+  return checks;
+}
+
+// Hides the shops where the user's staff account is disabled, unless --all; total stays the server's count.
+async function listShops(options = {}, env = process.env) {
+  const name = typeof options.name === 'string' ? options.name.trim() : '';
+  const page = await account.listShops({
+    ...(name ? { name } : {}), pageNum: options.pageNo ?? 1, pageSize: options.pageSize ?? 20,
+    lineOfBusinesses: options.lineOfBusiness ?? account.defaultLineOfBusinesses
+  }, env);
+  // Staff filtering may hide the entire page; only the server's unfiltered total determines continuation.
+  const hasMore = page.total === null ? null :
+    BigInt(page.pageNum) * BigInt(page.pageSize) < BigInt(page.total);
+  Object.assign(page, { hasMore,
+    nextPageNo: hasMore === true && page.pageNum < Number.MAX_SAFE_INTEGER ? page.pageNum + 1 : null,
+    windowLimitReached: hasMore !== false && page.pageNum === Number.MAX_SAFE_INTEGER });
+  if (options.all) return { ...page, totalScope: 'before_staff_filter', hidden: 0,
+    hiddenReason: null, nextStep: null, unchecked: [], uncheckedReason: null };
+  const checks = await checkStaffStatuses(page.items, env);
+  const items = page.items.filter((_, index) => checks[index].status !== account.staffStatuses.disabled);
+  const unchecked = page.items.filter((_, index) => checks[index].error).map(item => item.kdtId);
+  const failed = checks.find(check => check.error);
+  const hidden = page.items.length - items.length;
+  return {
+    ...page, items, totalScope: 'before_staff_filter', hidden,
+    hiddenReason: hidden ? 'staff_disabled' : null,
+    nextStep: hidden ? '本页隐藏了员工账号已停用的店铺；可加 --all 查看，但不能据此获得业务访问权限。' : null,
+    unchecked,
+    uncheckedReason: failed ? failed.error.message : null
+  };
+}
+
+// Confirms the shop through the user's own shop list before saving it as the context.
+async function useShop(kdtId, env = process.env) {
+  if (typeof kdtId !== 'string' || !idPattern.test(kdtId) || !Number.isSafeInteger(Number(kdtId))) {
+    throw new Error('kdtId 必须是正整数店铺 ID。');
+  }
+  const user = await account.whoami(env);
+  const page = await account.listShops({ includeKdtIds: [kdtId], pageNum: 1, pageSize: 1 }, env);
+  const shop = page.items.find(item => item.kdtId === kdtId);
+  if (!shop) {
+    throw new Error(`当前账号下没有可选店铺 ${kdtId}。执行 zan-saas shop list 查看可选店铺。`);
+  }
+  if (!shop.orgType) {
+    throw new Error(`店铺 ${kdtId} 是${roleLabel(shop.shopRole)}，暂时只能选择总部或单店。`);
+  }
+  // A failed check does not block: the business gateway still verifies the user against the shop.
+  const status = await account.staffStatus(kdtId, env).catch(() => null);
+  if (status === account.staffStatuses.disabled) {
+    throw new Error(`你在店铺 ${kdtId} 的员工账号已停用，不能选择。`);
+  }
+  const context = saveContext({ userId: user.userId, hq: kdtId, shopId: kdtId, orgType: shop.orgType },
+    { shopName: shop.shopName }, env);
+  return { context, shopName: shop.shopName, overriddenByEnv: Boolean(env.ZAN_SAAS_CONTEXT) };
+}
+
+function currentShop(env = process.env) {
+  const savedEntry = readSavedContext(env);
+  const saved = savedEntry ? { context: savedEntry.context, shopName: savedEntry.shopName } : null;
+  const requestShopId = requestShopIdOf(env);
+  if (env.ZAN_SAAS_CONTEXT) {
+    const state = readContext(env.ZAN_SAAS_CONTEXT);
+    return { source: 'env', status: state.status, context: state.context ?? null, saved, requestShopId };
+  }
+  return saved ? { source: 'saved', status: 'ready', context: saved.context, saved, requestShopId } :
+    { source: 'missing', status: 'missing', context: null, saved: null, requestShopId };
+}
+
+function clearShop(env = process.env) {
+  return { cleared: deleteContext(env), server: oauthConfig(env).server };
+}
+
+const describe = (context, shopName) =>
+  `${shopName || '未命名店铺'}（kdtId ${context.shopId}，${orgLabels[context.orgType]}）`;
+
+const text = {
+  list: (value, current) => {
+    const lines = value.items.map(item => `${item.kdtId === current ? '*' : ' '} ${item.kdtId}  ` +
+      `${item.shopName || '未命名店铺'}  类型：${roleLabel(item.shopRole)}${item.orgType ? '' : '（暂不可选）'}`);
+    if (lines.length) lines.push(value.total === null
+      ? `总数未知，第 ${value.pageNum} 页。* 为当前店铺。`
+      : `匹配总数 ${value.total} 个（员工停用过滤前），第 ${value.pageNum} 页。* 为当前店铺。`);
+    else if (!value.hidden) lines.push(value.total === 0 ? '没有找到店铺。' : '本页没有可显示的店铺。');
+    if (value.hidden) lines.push(`本页隐藏了 ${value.hidden} 个你已被停用的店铺，加 --all 显示全部。`);
+    if (value.unchecked?.length) {
+      lines.push(`${value.unchecked.length} 个店铺的员工状态查询失败，未过滤：${value.uncheckedReason}`);
+    }
+    if (value.hasMore === null) lines.push('总数未知，无法确认是否查完；可缩小名称筛选继续查找。');
+    if (Number.isSafeInteger(value.nextPageNo)) {
+      lines.push(`还有下一页；保留本次筛选和每页数量，加 --page-no ${value.nextPageNo} 继续。`);
+    }
+    if (value.windowLimitReached) lines.push('已达 CLI 页码上限，不能继续翻页；请缩小名称筛选。');
+    if (value.items.some(item => item.orgType)) lines.push(shopSelectionHint);
+    return lines.join('\n');
+  },
+  use: value => `${value.overriddenByEnv ? '已保存店铺' : '已切换到店铺'} ${describe(value.context, value.shopName)}。` +
+    (value.overriddenByEnv ? `\n${envNote}` : '') +
+    '\n确认当前店铺：zan-saas shop current',
+  current: value => {
+    const requestNote = value.requestShopId
+      ? `\n环境变量 ZAN_SAAS_KDT_ID 设置为 ${value.requestShopId}；具体请求店铺以所用命令和目标参数为准。`
+      : '';
+    if (value.source === 'env') {
+      const head = value.status === 'ready'
+        ? `当前上下文来自环境变量 ZAN_SAAS_CONTEXT（kdtId ${value.context.shopId}，${orgLabels[value.context.orgType]}）。`
+        : '环境变量 ZAN_SAAS_CONTEXT 无效，业务命令会拒绝执行。';
+      return `${value.saved ? `${head}\n已保存的店铺 ${describe(value.saved.context, value.saved.shopName)} 被它覆盖。` : head}${requestNote}`;
+    }
+    if (value.source === 'saved') {
+      return `当前店铺：${describe(value.context, value.saved.shopName)}${requestNote}\n${shopSelectionHint}`;
+    }
+    return `未选择店铺。${requestNote}\n${shopSelectionHint}`;
+  },
+  clear: value => (value.cleared ? '已清除保存的店铺。' : '没有保存的店铺。')
+};
+const printer = createPrinter(text);
+
+const defaults = {
+  list: options => listShops(options), use: kdtId => useShop(kdtId), current: () => currentShop(),
+  clear: () => clearShop(), currentShopId: () => shopIdOf(process.env)
+};
+
+function createShopCommand(impl = defaults) {
+  const shop = new Command('shop').description('查看可用店铺并设置当前店铺')
+    .addHelpText('after', `
+登录成功后，首次选店或切换店铺使用同一流程，无需重新登录：
+  1. 查看可选店铺：zan-saas shop list
+  2. 用户选定目标后：zan-saas shop use <kdtId>
+  3. 确认当前店铺：zan-saas shop current
+将 <kdtId> 替换为目标店铺 ID；店铺较多时可用 shop list --name <keyword> 查找。
+浏览器中切换店铺不会改变 CLI 保存的选择。
+ZAN_SAAS_CONTEXT 会覆盖保存的店铺，切换后以 shop current 显示的实际来源为准。
+`);
+  withSystemSchema(shop.command('list')
+    .description('分页查看当前用户的店铺，无需预先选择店铺')
+    .option('--name <keyword>', '按店铺名称关键字筛选')
+    .option('--page-no <n>', '页码，从 1 开始', positiveInteger('--page-no'), 1)
+    .option('--page-size <n>', '每页数量，1 到 50', positiveInteger('--page-size', 50), 20)
+    .option('--line-of-business <codes>', '逗号分隔的业务线编码，默认微商城、教育、酒店、餐饮、美业、零售',
+      lineOfBusinesses)
+    .option('--all', '显示全部店铺，包括你已被停用的店铺')
+    .addOption(formatOption())
+    .addHelpText('after', `
+结果按总部聚合，每行是一个总部或单店。目前只能选择总部或单店。
+默认逐个查询你在本页店铺的员工状态，隐藏已停用的店铺；查询失败的店铺保留。
+total 是员工停用过滤前的匹配总数；null 表示未知，空页或短页不表示已查完。
+hasMore 为 true 时，保留筛选和每页数量，按 nextPageNo 继续；为 null 时无法确认是否查完。
+windowLimitReached 为 true 表示达到 CLI 可表示的页码上限，请缩小筛选；不自动翻页。
+人机交接：Agent 展示可选店铺名称和类型，由用户选择；内部使用对应 kdtId；Agent 再执行 zan-saas shop use <kdtId>，并用 zan-saas shop current 核对实际生效的店铺，不自行猜选店铺或自动选第一家。
+调用账号接口网关，默认生产环境，ZAN_SAAS_ACCOUNT_API_BASE_URL 可以覆盖。
+`)
+    .action(async options => {
+      printer('list', options.format)(await impl.list(options), impl.currentShopId());
+    }), 'shop.list');
+  withSystemSchema(shop.command('use')
+    .description('选择当前用户的店铺并保存为上下文')
+    .argument('<kdtId>', 'shop list 返回的总部或单店 kdtId')
+    .addOption(formatOption())
+    .addHelpText('after', `
+先确认店铺属于当前账号，再把 userId、hq、shopId、orgType 保存到本地；业务命令随后用它选择店铺。
+已有有效上下文时沿用当前店铺；用户按店名明确选择且唯一匹配，或确认候选后，使用对应 kdtId 执行；本地上下文不是业务接口授权证明。
+环境变量 ZAN_SAAS_CONTEXT 设置时优先于保存的店铺。
+`)
+    .action(async (kdtId, options) => { printer('use', options.format)(await impl.use(kdtId)); }), 'shop.use');
+  withSystemSchema(shop.command('current')
+    .description('查看业务命令使用的店铺上下文，不访问网络')
+    .addOption(formatOption())
+    .action(options => { printer('current', options.format)(impl.current()); }), 'shop.current');
+  withSystemSchema(shop.command('clear')
+    .description('清除本机保存的店铺上下文，不访问网络')
+    .addOption(formatOption())
+    .action(options => { printer('clear', options.format)(impl.clear()); }), 'shop.clear');
+  return shop;
+}
+
+module.exports = { clearShop, createShopCommand, currentShop, listShops, text, useShop };

package/src/commands/system/skills.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { Command } = require('commander');
+const { readPublishedSkillFile } = require('../../cli/skill-catalog');
+const { skillsRoot } = require('../../cli/domain-catalog');
+const { withSystemSchema } = require('./contracts');
+
+function createSkillsCommand(catalog, root = skillsRoot) {
+  const skills = new Command('skills').description('查看使用指引')
+    .addHelpText('after', `
+示例：
+  zan-saas skills list
+  zan-saas skills read zan-saas
+`);
+  withSystemSchema(skills.command('list')
+    .description('列出当前安装版附带的使用指引')
+    .action(() => {
+      const entries = catalog.map(({ name, type, domain, description }) => ({
+        name, ...(domain ? { domain } : {}), description, type
+      }));
+      process.stdout.write(`${JSON.stringify({ skills: entries })}\n`);
+    }), 'skills.list');
+  withSystemSchema(skills.command('read')
+    .description('读取已发布的使用指引或其参考文档')
+    .argument('<skill>', 'skills list 返回的指引名称')
+    .argument('[file]', '相对 Markdown 路径，默认 SKILL.md')
+    .addHelpText('after', `
+指引名称和文件路径是两个独立参数，不要用同一对引号包住。
+
+示例：
+  zan-saas skills read zan-saas
+  zan-saas skills read zan-saas references/host-entry.md
+`)
+    .action((skill, file) => {
+      if (/\s/.test(skill)) {
+        const parts = skill.trim().split(/\s+/);
+        const entry = file === undefined && parts.length === 2 &&
+          catalog.find(entry => entry.name === parts[0] && entry.files.includes(parts[1]));
+        const example = entry && /^[a-zA-Z0-9._/-]+$/.test(parts[1])
+          ? `正确写法：zan-saas skills read ${entry.name} ${parts[1]}`
+          : '用法：zan-saas skills read <skill> [file]';
+        throw new Error(`请将 Skill 名称和文件路径分开传入，不要用同一对引号包住。${example}`);
+      }
+      process.stdout.write(readPublishedSkillFile(root, catalog, skill, file));
+    }), 'skills.read');
+  return skills;
+}
+
+module.exports = { createSkillsCommand };

package/src/execution/beijing-date-time.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const fullMilliseconds = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})\.(\d{3})$/;
+
+function isBeijingDateTimeMs(value) {
+  if (typeof value !== 'string') return false;
+  const match = fullMilliseconds.exec(value);
+  if (!match || match[0] !== value) return false;
+  const [year, month, day, hour, minute, second, millisecond] = match.slice(1).map(Number);
+  if (year < 1 || month < 1 || month > 12 || day < 1 || hour > 23 || minute > 59 || second > 59) {
+    return false;
+  }
+  const calendar = new Date(0);
+  calendar.setUTCFullYear(year, month - 1, day);
+  calendar.setUTCHours(hour, minute, second, millisecond);
+  return calendar.getUTCFullYear() === year && calendar.getUTCMonth() === month - 1 &&
+    calendar.getUTCDate() === day;
+}
+
+function fromBeijingSeconds(value) {
+  if (typeof value !== 'string' || value.length !== 19 || !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)) {
+    throw new TypeError('Invalid Beijing date-time');
+  }
+  const result = `${value}.000`;
+  if (!isBeijingDateTimeMs(result)) throw new TypeError('Invalid Beijing calendar date');
+  return result;
+}
+
+module.exports = { isBeijingDateTimeMs, fromBeijingSeconds };

package/src/execution/beijing-time.js

@@ -0,0 +1,21 @@
+'use strict';
+
+function formatBeijingMilliseconds(milliseconds) {
+  if (!Number.isSafeInteger(milliseconds)) throw new Error('invalid milliseconds');
+  const shifted = milliseconds + 8 * 3600 * 1000;
+  if (!Number.isSafeInteger(shifted)) throw new Error('invalid milliseconds');
+  const text = new Date(shifted).toISOString();
+  if (!/^\d{4}-/.test(text)) throw new Error('date outside four-digit year range');
+  return text.slice(0, 23).replace('T', ' ');
+}
+
+function isBeijingDateTimeMilliseconds(value) {
+  if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/.test(value)) return false;
+  try {
+    return formatBeijingMilliseconds(Date.parse(value.replace(' ', 'T') + '+08:00')) === value;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { formatBeijingMilliseconds, isBeijingDateTimeMilliseconds };

package/src/execution/bounded-input.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const { constants } = require('node:fs');
+const { TextDecoder } = require('node:util');
+const { parseExactJson } = require('./exact-json');
+
+const INPUT_LIMIT = 64 * 1024;
+
+async function readJsonInput(filename, { stdin = process.stdin, limit = INPUT_LIMIT } = {}) {
+  let handle;
+  const chunks = [];
+  let bytes = 0;
+  function append(chunk) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    bytes += buffer.length;
+    if (bytes > limit) throw new Error('input limit');
+    chunks.push(buffer);
+  }
+  try {
+    if (filename === '-') {
+      if (stdin.isTTY) throw new Error('input required');
+      for await (const chunk of stdin) append(chunk);
+    } else {
+      handle = await fs.open(filename, constants.O_RDONLY | constants.O_NONBLOCK);
+      const stat = await handle.stat();
+      if (!stat.isFile() || stat.size > limit) throw new Error('input file');
+      while (true) {
+        const buffer = Buffer.alloc(Math.min(4096, limit - bytes + 1));
+        const { bytesRead } = await handle.read(buffer);
+        if (bytesRead === 0) break;
+        append(buffer.subarray(0, bytesRead));
+      }
+    }
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
+    return parseExactJson(text, undefined, { rejectDuplicates: true });
+  } finally {
+    if (handle) await handle.close();
+  }
+}
+
+module.exports = { readJsonInput, INPUT_LIMIT };