cloudhouse-admin-cli 0.3.3

package/src/flags.mjs

@@ -0,0 +1,114 @@
+/**
+ * flag 词表：`argv.mjs` 只做机械切分，本模块负责「认不认识这个 flag」与「它该不该有值」。
+ *
+ * 为什么显式写表而不是运行时扫源码：启动不依赖文件系统、表本身可读可 grep，
+ * 代价（新加 flag 必须登记）由 `test/flags.test.mjs` 双向核对来付——
+ * 漏登记与陈旧登记都会被测试拦下，不会退化成又一次静默丢失。
+ *
+ * 0.2.0 参数策略：
+ *   VALUE_FLAGS 收到布尔（即 `--flag` 后面没有取值，或取值以 `-` 开头）→ exit 2；
+ *   未登记、不适用的 flag 与多余位置参数 → 请求前 exit 2；
+ *   `ch api` 是逃生舱，两个检查都跳过，否则未文档化的新端点参数会被本地拦死。
+ */
+import { usageError } from './errors.mjs'
+
+/** 必须取值的 flag：丢了取值就等于丢了筛选条件或写进错数据，绝不能静默 */
+export const VALUE_FLAGS = new Set([
+  // 全局
+  'profile', 'base-url', 'timeout', 'scope', 'cursor', 'filters', 'enabled',
+  // 载荷与请求构造
+  'data', 'd', 'q', 'H', 'reason', 'request-id', 'page', 'size', 'page-size', 'group-id',
+  // 账号 / 申请 / 个人资料
+  'studentNo', 'password', 'admin-level', 'real-name', 'authorized-group-ids', 'count',
+  'apply-group-id', 'position-code', 'phone',
+  // 候选人
+  'keyword', 'status', 'second-round-group-id', 'third-round-group-id',
+  'third-round-choice-state', 'starred-admin-id', 'starred-by-me', 'group-ids', 'version',
+  // 组别 / 方案 / 场次
+  'group-name', 'requirement', 'introduction', 'round', 'scope-group-id', 'assessment-content',
+  'assessment-image-url', 'assessment-file-url', 'assessment-file-name', 'pass-text-content',
+  'pass-image-url', 'fail-text-content', 'fail-image-url', 'booking-start-time', 'booking-end-time',
+  'publish-time', 'publish-mode', 'plan-id', 'slot-time', 'location', 'capacity',
+  // 面试 / 评价 / 现场助手
+  'slot', 'slot-id', 'interview-id', 'result', 'remark', 'content', 'score', 'evaluation-content',
+  // 通知
+  'title', 'notice-level', 'scope-type', 'target-round', 'target-group-id', 'target-slot-id',
+  'start-time', 'end-time',
+  // 上传 / 下载
+  'file', 'name', 'out',
+  // 数据型布尔：必须写明确取值。归到取值型而不是开关型，`--starred maybe` 才会
+  // 当场报错，而不是把 maybe 甩给位置参数、自己退化成 starred:true。
+  'starred', 'paused',
+  // AI Coding
+  'opens-at', 'closes-at', 'publish-at', 'survey-seconds', 'coding-seconds', 'reflection-seconds',
+  'reflection-mode', 'assignment-version', 'expected-revision', 'key-version', 'api-key',
+  'public-comment', 'internal-comment', 'state', 'grade-state', 'eligibility', 'ids',
+  // 签到快照
+  'screen-token',
+])
+
+/** 可裸写的开关；带取值时也接受（`--public=false`），取值按 parseBoolFlag 判定 */
+export const BOOL_FLAGS = new Set([
+  'pretty', 'json', 'help', 'public', 'show-token', 'force', 'allow-profile-mismatch', 'all',
+])
+
+export function isKnownFlag(name) {
+  return VALUE_FLAGS.has(name) || BOOL_FLAGS.has(name)
+}
+
+/** Usage metadata is also the executable parameter contract. */
+const GLOBAL_FLAGS = ['pretty', 'json', 'help', 'profile', 'base-url', 'timeout', 'allow-profile-mismatch']
+const PLAN_FIELDS = ['assessment-content', 'assessment-image-url', 'assessment-file-url', 'assessment-file-name', 'pass-text-content', 'pass-image-url', 'fail-text-content', 'fail-image-url', 'booking-start-time', 'booking-end-time', 'publish-time', 'publish-mode', 'status']
+const AI_FIELDS = ['name', 'group-ids', 'opens-at', 'closes-at', 'publish-at', 'survey-seconds', 'coding-seconds', 'reflection-seconds', 'reflection-mode']
+const EXTRAS = {
+  'plans update': PLAN_FIELDS,
+  'notifications update': ['notice-level', 'target-round', 'target-group-id', 'target-slot-id', 'status'],
+  'ai plans:update': AI_FIELDS,
+  'ai plans:credential': ['key-version'],
+  'ai attempts:grade': ['expected-revision'],
+  'uploads attachment-download': ['force'],
+  'uploads image': ['file'],
+  'uploads assessment': ['file'],
+  'uploads ai-attachment': ['file'],
+}
+export function usageLines(spec) {
+  return (Array.isArray(spec.usage) ? spec.usage : String(spec.usage || '').split('\n')).map(s => s.trim())
+}
+function selectedUsage(spec, positionals) {
+  const rows = usageLines(spec)
+  const prefix = `ch ${spec.name} `
+  return rows.find(s => s.startsWith(`${prefix}${positionals[0]} `) || s === `${prefix}${positionals[0]}`) || rows[0] || ''
+}
+export function supportedFlags(spec, positionals = []) {
+  const text = positionals.length ? selectedUsage(spec, positionals) : usageLines(spec).join(' ')
+  const names = new Set([...GLOBAL_FLAGS, ...(spec.allowedFlags || []), ...(EXTRAS[spec.name] || []), ...(EXTRAS[`${spec.name}:${positionals[0]}`] || [])])
+  for (const m of text.matchAll(/(?:^|[\s\[])--?([A-Za-z][\w-]*)/g)) names.add(m[1])
+  const action = positionals[0]
+  const writes = (spec.endpoints || []).some(e => !e.startsWith('GET ')) && !['list', 'get', 'get-generation'].includes(action)
+  const payloadCommand = /^(?:ai (?:plans|attempts|candidates|papers)|(?:plans|groups|slots|notifications|accounts) (?:create|update|batch|reset-password|status)|profile (?:update|change-password)|applies (?:submit|reject)|candidates (?:set-third-round-choice|star|update|application-status|set-second-round-groups|unbind-wechat)|evaluations add|interviews (?:result|attendance|reschedule|batch-result)|assistant submit)$/.test(spec.name)
+  if (writes && payloadCommand) { names.add('d'); names.add('data') }
+  if (spec.requestId && writes) { names.add('request-id'); names.add('version') }
+  return names
+}
+export function expectedPositionals(spec, positionals = []) {
+  const rows = spec.name && positionals.length ? [selectedUsage(spec, positionals)] : usageLines(spec)
+  return Math.max(0, ...rows.map(line => {
+    const clean = line.split('   #')[0].replace(/(^|[\s\[])--?[\w-]+\s+<[^>]+>/g, '$1').replace(/\[[^\]]*\]/g, '')
+    const placeholders = (clean.match(/<[^>\s]+>/g) || []).length
+    if (!spec.name) return placeholders
+    const tail = clean.startsWith(`ch ${spec.name}`) ? clean.slice(`ch ${spec.name}`.length).trim() : ''
+    const action = tail && !tail.startsWith('<') && !tail.startsWith('-') ? 1 : 0
+    return placeholders + action
+  }))
+}
+export function checkFlags({ entries, spec, positionals = [] }) {
+  if (spec.permissiveFlags) return []
+  const supported = supportedFlags(spec, positionals)
+  for (const [name, value] of entries) {
+    if (VALUE_FLAGS.has(name) && value === true) throw usageError(`--${name} 需要取值`, `写成 --${name} <值> 或 --${name}=<值>`)
+    if (!supported.has(name)) throw usageError(`未识别的 flag 或不适用于 ${spec.name}：--${name}`, '用 ch help <命令> 核对参数；已阻止发送请求')
+  }
+  const expected = expectedPositionals(spec, positionals)
+  if (positionals.length > expected) throw usageError(`${spec.name} 只使用 ${expected} 个位置参数，多余参数已拒绝`, '用 ch help <命令> 核对用法')
+  return []
+}

package/src/idempotent.mjs

@@ -0,0 +1,75 @@
+/**
+ * 幂等与版本重试（对齐 admin-web lib/idempotency.ts 语义）：
+ * - requestId 只对 `ch ai *` 写操作有意义：全仓只有 backend/aicoding 读 body.requestId 并去重，
+ *   interviews / plans / slots 等端点的审计 requestId 由服务端自己生成（AdminInterviewAuditContext），
+ *   客户端传了也不被读取，所以那些命令上的 --request-id 会被 CLI 直接拒绝而不是静默丢弃。
+ * - AI 写操作默认每次生成新 requestId；--request-id 可复用（服务端去重返回首个结果）
+ * - 4xx（非 429）为确定性拒绝：换 requestId 视为新操作
+ * - VERSION_CONFLICT / GRADE_VERSION_CONFLICT：仅当 version 由 CLI 本轮自读时，重读后以新 requestId 重试；
+ *   显式传入的 version 绝不自动重试（不把调用方意图变成隐式覆盖）
+ */
+import { randomUUID } from 'node:crypto'
+
+import { CliError } from './errors.mjs'
+
+export function newRequestId() {
+  return randomUUID()
+}
+
+export function isDefinitiveRejection(err) {
+  if (!(err instanceof CliError)) return false
+  if (err.httpStatus === null) return false
+  return err.httpStatus >= 400 && err.httpStatus < 500 && err.httpStatus !== 429
+}
+
+export function isVersionConflict(err) {
+  return err instanceof CliError && (err.reasonCode === 'VERSION_CONFLICT' || err.reasonCode === 'GRADE_VERSION_CONFLICT')
+}
+
+function currentVersionOf(err) {
+  const payload = err && err.payload
+  if (!payload || typeof payload !== 'object') return null
+  for (const key of ['currentVersion', 'version', 'expectedRevision', 'latestVersion']) {
+    if (typeof payload[key] === 'number') return payload[key]
+  }
+  return null
+}
+
+/**
+ * @param {object} options
+ * @param {number|undefined} options.explicitVersion 调用方显式传入的 version（存在则不自动重试）
+ * @param {string|null} [options.explicitRequestId] 调用方用 --request-id 指定的 id，只作用于首次请求
+ * @param {() => Promise<number>} options.readVersion 从服务端重读最新 version
+ * @param {({requestId:string|null, version:number}) => Promise<unknown>} options.run 实际写操作
+ * @param {number} [options.maxRetries] 最大自动重试次数（默认 2）
+ * @param {(message:string) => void} [options.log] stderr 进度日志
+ */
+export async function runWithVersionRetry({ explicitVersion, explicitRequestId = null, readVersion, run, maxRetries = 2, log = () => {} }) {
+  if (explicitVersion !== undefined) {
+    return run({ requestId: explicitRequestId || newRequestId(), version: Number(explicitVersion) })
+  }
+  let attempt = 0
+  for (;;) {
+    const version = await readVersion()
+    // 重试必须换 requestId：版本冲突重试的 body 里 version 一定变了，而后端
+    // AiCodingOperations.replay() 对「同 requestId + 不同 bodyHash」直接抛
+    // IDEMPOTENCY_CONFLICT——沿用调用方给的 id 会让自动重试永远失败。
+    const requestId = attempt === 0 ? explicitRequestId || newRequestId() : newRequestId()
+    if (attempt > 0 && explicitRequestId) {
+      log(`本次重试用新的 requestId（--request-id ${explicitRequestId} 只作用于首次请求；同 id 配不同 body 会被判 IDEMPOTENCY_CONFLICT）`)
+    }
+    try {
+      return await run({ requestId, version })
+    } catch (err) {
+      if (isVersionConflict(err) && attempt < maxRetries) {
+        attempt += 1
+        const current = currentVersionOf(err)
+        log(
+          `版本冲突（服务端当前版本：${current ?? version}），自动重读重试 ${attempt}/${maxRetries}`,
+        )
+        continue
+      }
+      throw err
+    }
+  }
+}

package/src/output.mjs

@@ -0,0 +1,138 @@
+/**
+ * 输出层：stdout 只承载稳定的 JSON 信封（Agent 契约），人类可读渲染走 --pretty。
+ * stderr 只承载进度/提示，绝不混入 stdout。
+ */
+
+/** 递归排序对象键，保证 JSON 输出稳定可 diff */
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[key])
+    return out
+  }
+  return value
+}
+
+export function stableStringify(value) {
+  return JSON.stringify(sortKeys(value))
+}
+
+const WIDE_CHAR = /[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6]/
+
+function displayWidth(text) {
+  let width = 0
+  for (const ch of String(text)) width += WIDE_CHAR.test(ch) ? 2 : 1
+  return width
+}
+
+function truncate(text, maxWidth) {
+  const s = String(text)
+  if (displayWidth(s) <= maxWidth) return s
+  let out = ''
+  let width = 0
+  for (const ch of s) {
+    const w = WIDE_CHAR.test(ch) ? 2 : 1
+    if (width + w > maxWidth - 1) break
+    out += ch
+    width += w
+  }
+  return `${out}…`
+}
+
+function pad(text, width) {
+  const gap = width - displayWidth(text)
+  return gap > 0 ? text + ' '.repeat(gap) : text
+}
+
+function scalarText(value) {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'object') return truncate(stableStringify(value), 48)
+  return truncate(value, 48)
+}
+
+function renderTable(rows, out) {
+  if (rows.length === 0) {
+    out.push('（无数据）')
+    return
+  }
+  const columns = []
+  const seen = new Set()
+  for (const row of rows) {
+    if (row && typeof row === 'object') {
+      for (const key of Object.keys(row)) {
+        if (!seen.has(key)) {
+          seen.add(key)
+          columns.push(key)
+        }
+      }
+    }
+  }
+  if (columns.length === 0) {
+    for (const row of rows) out.push(scalarText(row))
+    return
+  }
+  const widths = columns.map((key) => Math.max(displayWidth(key), ...rows.map((row) => displayWidth(scalarText(row && typeof row === 'object' ? row[key] : row)))))
+  out.push(columns.map((key, i) => pad(key, widths[i])).join('  '))
+  out.push(widths.map((w) => '─'.repeat(w)).join('  '))
+  for (const row of rows) {
+    out.push(columns.map((key, i) => pad(scalarText(row && typeof row === 'object' ? row[key] : row), widths[i])).join('  '))
+  }
+  out.push(`（共 ${rows.length} 行）`)
+}
+
+function renderValue(value, indent, out) {
+  const padStr = ' '.repeat(indent)
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      out.push(`${padStr}（无数据）`)
+      return
+    }
+    if (value.every((item) => item && typeof item === 'object')) {
+      renderTable(value, out)
+      return
+    }
+    for (const item of value) out.push(`${padStr}- ${scalarText(item)}`)
+    return
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value)
+    if (entries.length === 0) {
+      out.push(`${padStr}（空对象）`)
+      return
+    }
+    for (const [key, item] of entries) {
+      if (item && typeof item === 'object') {
+        out.push(`${padStr}${key}:`)
+        renderValue(item, indent + 2, out)
+      } else {
+        out.push(`${padStr}${pad(`${key}:`, Math.max(12, ...entries.map(([k]) => displayWidth(k)) + 1))} ${scalarText(item)}`)
+      }
+    }
+    return
+  }
+  out.push(`${padStr}${scalarText(value)}`)
+}
+
+/** --pretty 模式的人类可读渲染（表格/键值） */
+export function renderPretty(value) {
+  const out = []
+  renderValue(value, 0, out)
+  return out.join('\n')
+}
+
+/** 成功：stdout 输出信封 JSON 或 pretty 渲染（信封键序固定：ok → data；仅 data 负载递归排序保证稳定） */
+export function printSuccess(stdout, data, { pretty = false } = {}) {
+  if (pretty) {
+    stdout.write(`${renderPretty(data)}\n`)
+  } else {
+    stdout.write(`${JSON.stringify({ ok: true, data: sortKeys(data) })}\n`)
+  }
+}
+
+/** 失败：stdout 输出错误信封（保持 Agent 可解析），stderr 输出人读提示 */
+export function printFailure(stdout, stderr, error) {
+  const envelope = { ok: false, error: error.toJSON ? error.toJSON() : { code: 'UNKNOWN', message: String(error && error.message ? error.message : error) } }
+  stdout.write(`${JSON.stringify(envelope)}\n`)
+  if (error && error.hint) stderr.write(`提示：${error.hint}\n`)
+}

package/src/path.mjs

@@ -0,0 +1,40 @@
+import { usageError } from './errors.mjs'
+
+/**
+ * 路径参数的本地校验与编码。
+ *
+ * 背景：位置参数此前直接插值进 path 模板（55 处），只有 ai.mjs 的 modelId 与
+ * uploads 的 attachmentId 做了 encodeURIComponent。实测 `ch candidates get "42?foo=bar"`
+ * 发出的是 `/users/42?foo=bar/info`——new URL() 把尾随的 /info 当成了查询串的值，
+ * 请求形状被静默改掉且仍然带 JWT 打向真实端点。
+ *
+ * 后端所有传统端点的 @PathVariable 都是 Long（UserController / AdminController /
+ * InterviewController 等），AI Coding 的 plan/attempt/candidate id 也是 long，
+ * 因此数字校验放在本地既拦住了畸形输入，也避免了 Spring 类型转换那套更难读的报错。
+ */
+
+/** 数字型路径参数：后端 @PathVariable Long / long */
+export function idParam(raw, { label = 'id' } = {}) {
+  const text = String(raw ?? '').trim()
+  if (text === '') {
+    throw usageError(`缺少 ${label}`, `用法见 ch help，${label} 是正整数`)
+  }
+  if (!/^\d+$/.test(text)) {
+    throw usageError(`${label} 必须是正整数（收到：${text}）`, '路径参数只能是数字；若取值里带 ? # / 空格，说明拼错了或需要编码')
+  }
+  return text
+}
+
+/**
+ * 字符串型路径参数：允许文本，但必须逐段编码。
+ * allowEmpty 给「同一命令里 id 是否必填取决于 action」的多动作命令用
+ * （ch ai plans list 不带 id，ch ai plans get <id> 才带），缺失时交回调用方的显式检查。
+ */
+export function textParam(raw, { label = 'id', allowEmpty = false } = {}) {
+  const text = String(raw ?? '')
+  if (text.trim() === '') {
+    if (allowEmpty && raw === undefined) return undefined
+    throw usageError(`缺少 ${label}`)
+  }
+  return encodeURIComponent(text)
+}

package/src/payload.mjs

@@ -0,0 +1,137 @@
+import { readFileSync } from 'node:fs'
+
+import { usageError } from './errors.mjs'
+
+/**
+ * 写命令载荷构造。
+ * 语义化 flag 提供基础字段；`-d/--data`（JSON 或 @file）整体覆盖/扩展，
+ * 保证 Agent 对任意载荷字段有完全控制权（后端新增字段时 CLI 不落后）。
+ */
+
+/**
+ * 取 `-d/--data` 的文本：`@path` 视为文件，其余视为字面量。
+ * 文件读不到（ENOENT/EISDIR/权限）属于调用方写错了路径，必须是 exit 2，
+ * 不能让它冒泡成 exit 1 的业务错误——Agent 会据此以为后端出了问题而重试。
+ */
+export function readDataText(raw, { label = '-d/--data' } = {}) {
+  if (typeof raw !== 'string' || raw === '') {
+    throw usageError(`${label} 需要一个 JSON 参数`, `可用 ${label} '{"k":1}' 或 ${label} @payload.json`)
+  }
+  if (!raw.startsWith('@')) return raw
+  const file = raw.slice(1)
+  try {
+    return readFileSync(file, 'utf8')
+  } catch (err) {
+    throw usageError(`${label} 指定的文件无法读取：${file}（${err.code || err.message}）`, '检查路径是否存在、是否为可读的文本文件')
+  }
+}
+
+/** 解析 `-d/--data` 为任意 JSON 值（形状校验留给调用方） */
+export function parseDataJson(raw, { label = '-d/--data' } = {}) {
+  const text = readDataText(raw, { label })
+  try {
+    return JSON.parse(text)
+  } catch (err) {
+    throw usageError(`${label} 不是合法 JSON：${err.message}`, `可用 ${label} @payload.json 从文件读取`)
+  }
+}
+
+export function payloadFrom(ctx, base = {}) {
+  const raw = ctx.flags.get('data') ?? ctx.flags.get('d')
+  if (raw === undefined || raw === '') return base
+  const parsed = parseDataJson(raw)
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw usageError('-d/--data 必须是 JSON 对象')
+  }
+  return { ...base, ...parsed }
+}
+
+/** kebab-case flag → 驼峰字段名：flag 名与后端字段同名异形式，映射只写一处 */
+export function camelCase(flag) {
+  return flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+/**
+ * 逗号分隔的 id 列表 → 正整数数组。
+ * `split(',').map(Number)` 会把 'abc' 变成 NaN、把空段变成 0，而 JSON.stringify(NaN)
+ * 是 null：`--authorized-group-ids 1,abc,3` 实际发给后端的是 [1,null,3]，
+ * `"2, ,3"` 则是 [2,0,3]——授权到一个不存在的组别，还一路 exit 0。
+ */
+export function parseIdList(raw, { flag = 'group-ids', max = 200 } = {}) {
+  const parts = String(raw).split(',')
+  if (parts.length > max) {
+    throw usageError(`--${flag} 最多 ${max} 个（当前 ${parts.length} 个）`)
+  }
+  return parts.map((part) => {
+    const text = part.trim()
+    if (!/^\d+$/.test(text) || Number(text) < 1) {
+      throw usageError(
+        `--${flag} 含无效 id：${text === '' ? '（空段）' : text}`,
+        `用逗号分隔的正整数，如 --${flag} 1,2,3；不要留空段或尾随逗号`,
+      )
+    }
+    return Number(text)
+  })
+}
+
+/** 读取字符串 flag；required 时缺失抛用法错误 */
+export function flagString(ctx, name, { required = false, label } = {}) {
+  const value = ctx.flags.get(name)
+  if (typeof value !== 'string' || value === '') {
+    if (required) {
+      throw usageError(`缺少 --${name}`, label ? `用法：${label}` : undefined)
+    }
+    return undefined
+  }
+  return value
+}
+
+/** 读取数字 flag；required 时缺失抛用法错误，非数字抛用法错误 */
+export function flagNumber(ctx, name, { required = false, label } = {}) {
+  const value = ctx.flags.get(name)
+  if (value === undefined || value === true || value === '') {
+    if (required) throw usageError(`缺少 --${name}`, label ? `用法：${label}` : undefined)
+    return undefined
+  }
+  const num = Number(value)
+  if (!Number.isFinite(num)) throw usageError(`--${name} 不是有效数字：${value}`)
+  return num
+}
+
+/** 读取枚举 flag；不在候列举内抛用法错误 */
+export function flagEnum(ctx, name, choices, { required = false, label } = {}) {
+  const value = flagString(ctx, name, { required, label })
+  if (value === undefined) return undefined
+  if (!choices.includes(value)) {
+    throw usageError(`--${name} 必须是 ${choices.join(' / ')}之一（收到：${value}）`)
+  }
+  return value
+}
+
+/**
+ * 布尔取值解析：true|false|1|0|yes|no（大小写不敏感），其余一律用法错误。
+ * 之前有三套各自为政的解析（flagBool、candidates 内联、query.parseBool），
+ * 语义都不同且都把不认识的写法当成 false：`ch candidates star 1 --starred yes`
+ * 会提交 starred:false（与意图完全相反）并 exit 0。宁可直接报错。
+ */
+export function parseBoolFlag(value, { flag } = {}) {
+  const text = String(value).trim().toLowerCase()
+  if (text === 'true' || text === '1' || text === 'yes' || text === 'y' || text === 'on') return true
+  if (text === 'false' || text === '0' || text === 'no' || text === 'n' || text === 'off') return false
+  const label = flag ? `--${flag}` : '布尔参数'
+  throw usageError(`${label} 需要布尔取值（收到：${value}）`, '可用 true / false / 1 / 0 / yes / no')
+}
+
+/** 读取布尔 flag（--flag true|false，裸写视为 true，--no-flag 视为 false） */
+export function flagBool(ctx, name) {
+  const value = ctx.flags.get(name)
+  if (value === undefined) return undefined
+  if (value === true) return true
+  if (value === false) return false
+  return parseBoolFlag(value, { flag: name })
+}
+
+/** 布尔 flag 的存在性判定：`--show-token` / `--show-token=false` 都要给出正确答案 */
+export function flagOn(ctx, name) {
+  return flagBool(ctx, name) === true
+}

package/src/prompt.mjs

@@ -0,0 +1,47 @@
+import readline from 'node:readline'
+import { Writable } from 'node:stream'
+
+/** TTY 普通输入；提示走 stderr，保留 stdout 的机器可读信封。 */
+export function promptText(prompt) {
+  return new Promise((resolve, reject) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true })
+    rl.question(prompt, answer => { rl.close(); resolve(answer) })
+    rl.on('SIGINT', () => { rl.close(); reject(new Error('已取消输入')) })
+  })
+}
+
+/** 从 JWT payload 解码 exp（秒）→ epoch 毫秒；失败返回 null */
+export function decodeTokenExpiry(token) {
+  try {
+    const parts = String(token).split('.')
+    if (parts.length < 2) return null
+    const normalized = parts[1].replace(/-/g, '+').replace(/_/g, '/')
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=')
+    const payload = JSON.parse(Buffer.from(padded, 'base64').toString('utf8'))
+    return typeof payload.exp === 'number' && Number.isFinite(payload.exp) ? payload.exp * 1000 : null
+  } catch {
+    return null
+  }
+}
+
+export function sessionExpiryState(expiresAt, now = Date.now()) {
+  if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) return 'unknown'
+  const remaining = expiresAt - now
+  if (remaining <= 0) return 'expired'
+  if (remaining <= 15 * 60 * 1000) return 'expiring'
+  return 'ok'
+}
+
+/** 交互式密码输入：readline 的输出被静音，不依赖平台的 stty。 */
+export function promptPassword(prompt = '密码：', { input = process.stdin, output = process.stderr } = {}) {
+  return new Promise((resolve, reject) => {
+    const silent = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+    silent.isTTY = true
+    silent.columns = output.columns || 80
+    const rl = readline.createInterface({ input, output: silent, terminal: true })
+    output.write(prompt)
+    const finish = () => { rl.close(); silent.end(); output.write('\n') }
+    rl.question('', answer => { finish(); resolve(answer) })
+    rl.on('SIGINT', () => { finish(); reject(new Error('已取消输入')) })
+  })
+}

package/src/query.mjs

@@ -0,0 +1,44 @@
+/** 查询参数构造：flag → query key 的显式映射（与 api.ts 的参数名逐一对应） */
+import { CliError, usageError } from './errors.mjs'
+
+/**
+ * @param {object} ctx CLI 上下文（flags）
+ * @param {Record<string, {key?:string, parse?:(v:string)=>unknown}>} spec
+ * @returns {Array<[string, unknown]>}
+ */
+export function collectQuery(ctx, spec) {
+  const query = []
+  for (const [flagName, options] of Object.entries(spec)) {
+    const value = ctx.flags.get(flagName)
+    if (value === undefined || value === true || value === false || value === '') continue
+    const parse = options.parse || String
+    let parsed
+    try {
+      parsed = parse(value)
+    } catch (err) {
+      // 解析器可能抛普通 Error（如内联转换）；本地校验失败一律归为用法错误（exit 2）
+      if (err instanceof CliError) throw err
+      throw usageError(`--${flagName} 取值无效：${err && err.message ? err.message : err}`)
+    }
+    query.push([options.key || flagName, parsed])
+  }
+  return query
+}
+
+export function parseNumber(value) {
+  const num = Number(value)
+  if (!Number.isFinite(num)) {
+    throw usageError(`不是有效数字：${value}`, '数字型参数只接受纯数字，如 --page 2')
+  }
+  return num
+}
+
+/** 从 `-d/--data` 读取 JSON 载荷（支持 @file）；不存在返回 null */
+export function readDataPayload(ctx) {
+  const raw = ctx.flags.get('data') ?? ctx.flags.get('d')
+  if (raw === undefined) return null
+  if (raw === true) {
+    throw usageError('-d/--data 需要一个 JSON 参数', '可用 -d \'{"k":1}\' 或 -d @payload.json')
+  }
+  return raw
+}

package/src/sensitive.mjs

@@ -0,0 +1,50 @@
+import { usageError } from './errors.mjs'
+
+/**
+ * 敏感写操作的 reason 前置校验。
+ * 这些操作后端强制要求审计原因（三面改组、解绑微信、驳回申请、作废考次、
+ * 已公布评分修正、撤回计划、安排重考、轮换模型密钥）。CLI 在本地先行拦截，
+ * 缺 --reason 直接 exit 2，不消耗服务端配额、也不产生 4xx 噪音。
+ */
+export function requireReason(ctx, { max = 200, label } = {}) {
+  const value = ctx.flags.get('reason')
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw usageError(
+      '该操作必须提供 --reason（审计原因）',
+      label ? `用法：${label}` : undefined,
+    )
+  }
+  const reason = value.trim()
+  if (reason.length > max) {
+    throw usageError(`--reason 不能超过 ${max} 字（当前 ${reason.length} 字）`)
+  }
+  return reason
+}
+
+/**
+ * 可选的审计原因：允许不提供（返回 undefined，调用方不写这个键，由后端补默认文案），
+ * 但一旦提供就必须与 requireReason 同一套约束（非空、≤max 字）。
+ * `ch interviews attendance` 的 reason 在后端确实是可选的
+ * （AdminInterviewAttendanceController:74 把非字符串归一化成 null），
+ * 所以不能改成 requireReason——那会把合法操作变成拒绝。
+ * 但长度上限必须一致，否则一条 --reason x10000 会原样进审计日志。
+ */
+export function optionalReason(ctx, { max = 200, label } = {}) {
+  const value = ctx.flags.get('reason')
+  if (typeof value !== 'string' || value.trim() === '') return undefined
+  const reason = value.trim()
+  if (reason.length > max) {
+    throw usageError(
+      `--reason 不能超过 ${max} 字（当前 ${reason.length} 字）`,
+      label ? `用法：${label}` : undefined,
+    )
+  }
+  return reason
+}
+
+/** 声明某命令需要 reason（供 help 与契约守护测试使用） */
+export const REQUIRES_REASON_COMMANDS = new Set([
+  'candidates unbind-wechat',
+  'candidates third-round-choice',
+  'applies reject',
+])