cloudhouse-admin-cli 0.3.3

package/src/commands/plans.mjs

@@ -0,0 +1,90 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { collectQuery, parseNumber } from '../query.mjs'
+import { flagEnum, flagString, flagNumber, payloadFrom, camelCase } from '../payload.mjs'
+import { normalizeLocalTime } from '../time.mjs'
+import { idParam } from '../path.mjs'
+
+/** buildPlanPayload 读取的 flag 清单（词表守护测试的扫描面，见文件内注释） */
+const TEXT_FLAGS = ['assessment-image-url', 'assessment-file-url', 'assessment-file-name', 'pass-text-content', 'pass-image-url', 'fail-text-content', 'fail-image-url']
+const BOOKING_TIME_FLAGS = ['booking-start-time', 'booking-end-time', 'publish-time']
+
+register('plans list', {
+  summary: '考核方案列表（一面/二轮/三面方案）',
+  usage: 'ch plans list [--round 1|2|3] [--scope-group-id N] [--status 1|2] [--pretty]',
+  endpoints: ['GET /admin/interview-plans'],
+  run: async (ctx) => {
+    const query = collectQuery(ctx, {
+      round: { parse: parseNumber },
+      'scope-group-id': { key: 'scopeGroupId', parse: parseNumber },
+      status: { parse: parseNumber },
+    })
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/interview-plans', query })
+    return data
+  },
+})
+
+/** 构造方案载荷：语义 flag 为基础，-d 覆盖；时间统一本地无偏移格式 */
+function buildPlanPayload(ctx, { includeScope }) {
+  const base = {}
+  if (includeScope) {
+    const round = flagEnum(ctx, 'round', ['1', '2', '3'], { required: true, label: 'ch plans create --round 1|2|3' })
+    base.round = Number(round)
+    base.scopeGroupId = flagNumber(ctx, 'scope-group-id', { required: true, label: 'ch plans create --scope-group-id N' })
+  }
+  const assessmentContent = flagString(ctx, 'assessment-content', { required: includeScope, label: '--assessment-content 考核内容' })
+  if (assessmentContent !== undefined) base.assessmentContent = assessmentContent
+  // 显式常量而非内联字面量：src/flags.mjs 的词表守护测试只认顶层读取与 *_FLAGS 常量，
+  // 藏在 for-of 字面量里的 flag 名扫不到，就会退化成「拼错也不报」的静默丢失。
+  for (const flag of TEXT_FLAGS) {
+    const value = flagString(ctx, flag)
+    if (value !== undefined) base[flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = value
+  }
+  for (const flag of BOOKING_TIME_FLAGS) {
+    const value = flagString(ctx, flag)
+    if (value !== undefined) base[camelCase(flag)] = normalizeLocalTime(value)
+  }
+  const publishMode = flagEnum(ctx, 'publish-mode', ['REALTIME', 'SCHEDULED'])
+  if (publishMode !== undefined) base.publishMode = publishMode
+  const status = flagEnum(ctx, 'status', ['1', '2'])
+  if (status !== undefined) base.status = Number(status)
+  const payload = payloadFrom(ctx, base)
+  if (payload.publishMode === 'SCHEDULED' && !payload.publishTime) {
+    throw usageError('publishMode=SCHEDULED 时必须提供 --publish-time（或载荷中带 publishTime）')
+  }
+  return payload
+}
+
+register('plans create', {
+  summary: '创建考核方案',
+  usage: 'ch plans create --round 1|2|3 --scope-group-id N --assessment-content 内容 [--assessment-image-url U] [--assessment-file-url U] [--assessment-file-name 名] [--pass-text-content T] [--pass-image-url U] [--fail-text-content T] [--fail-image-url U] [--booking-start-time "2026-09-28 14:00"] [--booking-end-time "..."] [--publish-mode REALTIME|SCHEDULED] [--publish-time "..."] [-d json]',
+  endpoints: ['POST /admin/interview-plans'],
+  run: async (ctx) => {
+    const payload = buildPlanPayload(ctx, { includeScope: true })
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/interview-plans', body: payload })
+    return data
+  },
+})
+
+register('plans update', {
+  summary: '更新考核方案（未停用且无场次时可改）',
+  usage: 'ch plans update <planId> [--assessment-content 内容] [--status 1|2] [--publish-mode ...] [--publish-time ...] [-d json]',
+  endpoints: ['PUT /admin/interview-plans/{planId}'],
+  run: async (ctx) => {
+    const planId = idParam(ctx.positionals[0], { label: 'planId' })
+    const payload = buildPlanPayload(ctx, { includeScope: false })
+    const { data } = await ctx.client.request({ method: 'PUT', path: `/admin/interview-plans/${planId}`, body: payload })
+    return data
+  },
+})
+
+register('plans delete', {
+  summary: '删除已停用且无场次的考核方案',
+  usage: 'ch plans delete <planId>',
+  endpoints: ['DELETE /admin/interview-plans/{planId}'],
+  run: async (ctx) => {
+    const planId = idParam(ctx.positionals[0], { label: 'planId' })
+    const { data } = await ctx.client.request({ method: 'DELETE', path: `/admin/interview-plans/${planId}` })
+    return data === null ? { deleted: true, planId: Number(planId) } : data
+  },
+})

package/src/commands/profile.mjs

@@ -0,0 +1,43 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { flagString, flagNumber, payloadFrom } from '../payload.mjs'
+
+register('profile get', {
+  summary: '当前管理员个人资料',
+  usage: 'ch profile get',
+  endpoints: ['GET /admin/profile'],
+  run: async (ctx) => {
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/profile' })
+    return data
+  },
+})
+
+register('profile update', {
+  summary: '修改个人资料',
+  usage: 'ch profile update --real-name 姓名 [--group-id N] [--phone 手机号]',
+  endpoints: ['PUT /admin/profile'],
+  run: async (ctx) => {
+    const realName = flagString(ctx, 'real-name', { required: true, label: 'ch profile update --real-name 姓名' })
+    const base = { realName }
+    const groupId = flagNumber(ctx, 'group-id')
+    if (groupId !== undefined) base.groupId = groupId
+    const phone = flagString(ctx, 'phone')
+    if (phone !== undefined) base.phone = phone
+    const payload = payloadFrom(ctx, base)
+    const { data } = await ctx.client.request({ method: 'PUT', path: '/admin/profile', body: payload })
+    return data === null ? { updated: true } : data
+  },
+})
+
+register('profile change-password', {
+  summary: '修改当前账号登录密码',
+  usage: 'ch profile change-password --password 新密码',
+  endpoints: ['PUT /admin/profile/password'],
+  run: async (ctx) => {
+    const password = flagString(ctx, 'password', { required: true, label: 'ch profile change-password --password ******' })
+    if (password.length < 6) throw usageError('密码长度不能少于 6 位')
+    const payload = payloadFrom(ctx, { password })
+    const { data } = await ctx.client.request({ method: 'PUT', path: '/admin/profile/password', body: payload })
+    return data === null ? { updated: true } : data
+  },
+})

package/src/commands/slots.mjs

@@ -0,0 +1,95 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { collectQuery, parseNumber } from '../query.mjs'
+import { flagEnum, flagString, flagNumber, payloadFrom } from '../payload.mjs'
+import { normalizeLocalTime } from '../time.mjs'
+import { idParam } from '../path.mjs'
+
+register('slots list', {
+  summary: '面试场次列表',
+  usage: 'ch slots list [--round 1|2|3] [--scope-group-id N] [--plan-id N] [--status 1|2] [--pretty]',
+  endpoints: ['GET /admin/interview-slots'],
+  run: async (ctx) => {
+    const query = collectQuery(ctx, {
+      round: { parse: parseNumber },
+      'scope-group-id': { key: 'scopeGroupId', parse: parseNumber },
+      'plan-id': { key: 'planId', parse: parseNumber },
+      status: { parse: parseNumber },
+    })
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/interview-slots', query })
+    return data
+  },
+})
+
+register('slots qr', {
+  summary: '场次签到二维码/口令',
+  usage: 'ch slots qr <slotId>',
+  endpoints: ['GET /admin/interview-slots/{slotId}/checkin-qr'],
+  run: async (ctx) => {
+    const slotId = idParam(ctx.positionals[0], { label: 'slotId' })
+    const { data } = await ctx.client.request({ method: 'GET', path: `/admin/interview-slots/${slotId}/checkin-qr` })
+    return data
+  },
+})
+
+register('slots create', {
+  summary: '创建面试场次',
+  usage: 'ch slots create --plan-id N --slot-time "2026-09-28 14:00" --location 教学楼A301 --capacity 5',
+  endpoints: ['POST /admin/interview-slots'],
+  run: async (ctx) => {
+    const planId = flagNumber(ctx, 'plan-id', { required: true, label: 'ch slots create --plan-id N' })
+    const slotTime = flagString(ctx, 'slot-time', { required: true, label: 'ch slots create --slot-time "2026-09-28 14:00"' })
+    const location = flagString(ctx, 'location', { required: true, label: 'ch slots create --location 地点' })
+    const capacity = flagNumber(ctx, 'capacity', { required: true, label: 'ch slots create --capacity N' })
+    if (!Number.isInteger(capacity) || capacity <= 0) throw usageError('--capacity 必须是正整数')
+    const payload = payloadFrom(ctx, { planId, slotTime: normalizeLocalTime(slotTime), location, capacity })
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/interview-slots', body: payload })
+    return data
+  },
+})
+
+register('slots update', {
+  summary: '更新面试场次',
+  usage: 'ch slots update <slotId> [--slot-time "..."] [--location 地点] [--capacity N] [--status 1|2]',
+  endpoints: ['PUT /admin/interview-slots/{slotId}'],
+  run: async (ctx) => {
+    const slotId = idParam(ctx.positionals[0], { label: 'slotId' })
+    const base = {}
+    const slotTime = flagString(ctx, 'slot-time')
+    if (slotTime !== undefined) base.slotTime = normalizeLocalTime(slotTime)
+    const location = flagString(ctx, 'location')
+    if (location !== undefined) base.location = location
+    const capacity = flagNumber(ctx, 'capacity')
+    if (capacity !== undefined) {
+      if (!Number.isInteger(capacity) || capacity <= 0) throw usageError('--capacity 必须是正整数')
+      base.capacity = capacity
+    }
+    const status = flagEnum(ctx, 'status', ['1', '2'])
+    if (status !== undefined) base.status = Number(status)
+    const payload = payloadFrom(ctx, base)
+    const { data } = await ctx.client.request({ method: 'PUT', path: `/admin/interview-slots/${slotId}`, body: payload })
+    return data
+  },
+})
+
+register('slots close', {
+  summary: '关闭场次（停止预约）',
+  usage: 'ch slots close <slotId>',
+  endpoints: ['PUT /admin/interview-slots/{slotId}/close'],
+  run: async (ctx) => {
+    const slotId = idParam(ctx.positionals[0], { label: 'slotId' })
+    const { data } = await ctx.client.request({ method: 'PUT', path: `/admin/interview-slots/${slotId}/close` })
+    return data === null ? { closed: true, slotId: Number(slotId) } : data
+  },
+})
+
+register('slots delete', {
+  summary: '删除场次',
+  usage: 'ch slots delete <slotId>',
+  endpoints: ['DELETE /admin/interview-slots/{slotId}'],
+  run: async (ctx) => {
+    const slotId = idParam(ctx.positionals[0], { label: 'slotId' })
+    const { data } = await ctx.client.request({ method: 'DELETE', path: `/admin/interview-slots/${slotId}` })
+    return data === null ? { deleted: true, slotId: Number(slotId) } : data
+  },
+})

package/src/commands/uploads.mjs

@@ -0,0 +1,169 @@
+import path from 'node:path'
+import fs from 'node:fs'
+import crypto from 'node:crypto'
+
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { textParam } from '../path.mjs'
+import { flagString, flagOn } from '../payload.mjs'
+
+const MAX_IMAGE_SIZE = 2 * 1024 * 1024
+const MAX_ASSESSMENT_SIZE = 10 * 1024 * 1024
+
+/**
+ * 决定附件落盘位置。
+ * 之前是 `path.resolve(flags.get('out') || name)` 直接写：--name 是调用方（服务端按名
+ * 返回内容）给的，`--name ../../x.txt` 实测把远端内容写到了 cwd 之外；同名文件还会被
+ * 静默覆盖。现在默认名取 basename、必须落在 cwd 内，显式 --out 才允许落在别处，
+ * 覆盖必须 --force。
+ */
+function resolveDownloadTarget({ name, out, force }) {
+  if (out !== undefined && out !== false && out !== true && String(out).trim() !== '') {
+    const explicit = path.resolve(String(out))
+    if (!force && fs.existsSync(explicit)) {
+      throw usageError(`目标文件已存在：${explicit}`, '确认要覆盖请加 --force')
+    }
+    return explicit
+  }
+  const base = path.basename(String(name).trim())
+  if (base === '' || base === '.' || base === '..') {
+    throw usageError(`无法从 --name 推出安全文件名：${name}`, '请用 --out 指定完整输出路径')
+  }
+  const target = path.resolve(process.cwd(), base)
+  if (!force && fs.existsSync(target)) {
+    throw usageError(`目标文件已存在：${target}`, '确认要覆盖请加 --force，或用 --out 换个路径')
+  }
+  return target
+}
+
+const IMAGE_MIME_BY_EXTENSION = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.webp': 'image/webp',
+}
+
+/** 与 admin-web lib/assessmentFile.ts 的允许清单一致 */
+const ASSESSMENT_MIME_BY_EXTENSION = {
+  '.pdf': 'application/pdf',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.csv': 'text/csv',
+  '.md': 'text/markdown',
+  '.zip': 'application/zip',
+  '.rar': 'application/vnd.rar',
+  '.7z': 'application/x-7z-compressed',
+  '.tar': 'application/x-tar',
+}
+
+/** 读取待上传文件并做本地预检（格式/大小），失败按用法错误处理 */
+function readUploadFile(ctx, { mimeByExtension, maxSize, label }) {
+  const filePath = ctx.positionals[0] || flagString(ctx, 'file')
+  if (!filePath) throw usageError('缺少待上传文件路径', `用法：${label}`)
+  let stat
+  try {
+    stat = fs.statSync(filePath)
+  } catch {
+    throw usageError(`文件不存在：${filePath}`)
+  }
+  if (!stat.isFile()) throw usageError(`不是普通文件：${filePath}`)
+  if (stat.size === 0) throw usageError('文件不能为空')
+  if (stat.size > maxSize) {
+    throw usageError(
+      `文件大小 ${(stat.size / 1024 / 1024).toFixed(2)}MB 超过上限 ${maxSize / 1024 / 1024}MB`,
+      '管理台上传同样受限；请先压缩或裁剪',
+    )
+  }
+  const extension = path.extname(filePath).toLowerCase()
+  const mime = mimeByExtension[extension]
+  if (!mime) {
+    throw usageError(`不支持的文件格式 ${extension || '（无扩展名）'}`, `允许：${Object.keys(mimeByExtension).join(' ')}`)
+  }
+  const buffer = fs.readFileSync(filePath)
+  const fileName = path.basename(filePath)
+  const form = new FormData()
+  form.append('file', new Blob([buffer], { type: mime }), fileName)
+  return { form, fileName, size: stat.size }
+}
+
+/** 相对资源地址（/uploads/**）拼成绝对地址，便于跨域部署下直接使用 */
+function absoluteUrl(baseUrl, url) {
+  if (typeof url !== 'string' || !url.startsWith('/')) return url
+  try {
+    return new URL(url, baseUrl.replace(/\/api\/?$/, '/')).toString()
+  } catch {
+    return url
+  }
+}
+
+register('uploads image', {
+  summary: '上传图片（JPG/PNG/WebP，≤2MB）',
+  usage: 'ch uploads image <文件路径>',
+  endpoints: ['POST /admin/uploads'],
+  run: async (ctx) => {
+    const { form, fileName, size } = readUploadFile(ctx, {
+      mimeByExtension: IMAGE_MIME_BY_EXTENSION,
+      maxSize: MAX_IMAGE_SIZE,
+      label: 'ch uploads image <文件路径>',
+    })
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/uploads', formData: form })
+    return { ...data, fileName, size, absoluteUrl: absoluteUrl(ctx.config.baseUrl, data && data.url) }
+  },
+})
+
+register('uploads assessment', {
+  summary: '上传考核附件（PDF/DOC/DOCX/XLS/XLSX/CSV/ZIP/RAR/7Z/TAR/MD，≤10MB）',
+  usage: 'ch uploads assessment <文件路径>',
+  endpoints: ['POST /admin/uploads/assessment-files'],
+  run: async (ctx) => {
+    const { form, fileName, size } = readUploadFile(ctx, {
+      mimeByExtension: ASSESSMENT_MIME_BY_EXTENSION,
+      maxSize: MAX_ASSESSMENT_SIZE,
+      label: 'ch uploads assessment <文件路径>',
+    })
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/uploads/assessment-files', formData: form })
+    return { ...data, size, absoluteUrl: absoluteUrl(ctx.config.baseUrl, data && data.url) }
+  },
+})
+
+register('uploads ai-attachment', {
+  summary: '上传 AI Coding 题包附件（≤10MB）',
+  usage: 'ch uploads ai-attachment <文件路径>',
+  endpoints: ['POST /admin/ai-coding/paper-attachments'],
+  run: async (ctx) => {
+    const { form, fileName, size } = readUploadFile(ctx, {
+      mimeByExtension: ASSESSMENT_MIME_BY_EXTENSION,
+      maxSize: MAX_ASSESSMENT_SIZE,
+      label: 'ch uploads ai-attachment <文件路径>',
+    })
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/ai-coding/paper-attachments', formData: form })
+    return data
+  },
+})
+
+register('uploads attachment-download', {
+  summary: '下载 AI Coding 题包附件到本地文件',
+  usage: 'ch uploads attachment-download <attachmentId> --name 文件名 [--out 输出路径]',
+  endpoints: ['GET /admin/ai-coding/paper-attachments/{attachmentId}'],
+  run: async (ctx) => {
+    const [attachmentId] = ctx.positionals
+    if (!attachmentId) throw usageError('缺少 attachmentId', '用法：ch uploads attachment-download <attachmentId> --name 文件名')
+    const name = flagString(ctx, 'name', { required: true, label: '--name 附件名（服务端按名返回）' })
+    const { buffer, contentType } = await ctx.client.request({
+      method: 'GET',
+      path: `/admin/ai-coding/paper-attachments/${textParam(attachmentId, { label: 'attachmentId' })}`,
+      query: [['name', name]],
+      raw: true,
+    })
+    const outPath = resolveDownloadTarget({ name, out: ctx.flags.get('out'), force: flagOn(ctx, 'force') })
+    const temp = `${outPath}.partial-${crypto.randomUUID()}`
+    try {
+      fs.writeFileSync(temp, buffer, { flag: 'wx', mode: 0o600 })
+      if (flagOn(ctx, 'force')) fs.renameSync(temp, outPath)
+      else { fs.linkSync(temp, outPath); fs.unlinkSync(temp) }
+    } finally { try { fs.unlinkSync(temp) } catch {} }
+    return { savedTo: outPath, bytes: buffer.length, contentType }
+  },
+})

package/src/config.mjs

@@ -0,0 +1,68 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+import { usageError } from './errors.mjs'
+
+/** 内置 profile：优先级 flag > env > 配置文件 > 内置默认值 */
+export const BUILTIN_PROFILES = Object.freeze({
+  local: 'http://127.0.0.1:8080/api',
+  prod: 'https://api.dayunwu.cn/api',
+})
+export const DEFAULT_PROFILE = 'local'
+
+export function configDir(env = process.env) {
+  return env.CH_CONFIG_DIR || path.join(os.homedir(), '.config', 'cloudhouse-cli')
+}
+
+export function configFilePath(env = process.env) {
+  return path.join(configDir(env), 'config.json')
+}
+
+/** 读取用户配置文件（不存在或损坏时返回空对象，不阻断命令） */
+export function loadConfigFile(env = process.env) {
+  try {
+    const raw = fs.readFileSync(configFilePath(env), 'utf8')
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 解析运行配置。优先级：--flag > 环境变量 > 配置文件 > 内置默认。
+ *
+ * profile 拼错绝不能静默回落到 local：那会让一条以为在操作生产的写请求打到本地
+ * （或反过来），而调用方看到的仍然是 exit 0。只有在 baseUrl 已由 flag/env 显式
+ * 给出时，profile 才退化成一个标签；否则未知 profile 必须是用法错误。
+ *
+ * @returns {{profile:string, baseUrl:string, baseUrlSource:string}}
+ */
+export function resolveConfig({ flags = {}, env = process.env } = {}) {
+  const file = loadConfigFile(env)
+  const profile = String(flags.profile ?? env.CH_PROFILE ?? file.defaultProfile ?? DEFAULT_PROFILE)
+
+  const flagBase = flags.baseUrl
+  const envBase = env.CH_BASE_URL || env.CH_API_BASE
+  const fileProfiles = file.profiles && typeof file.profiles === 'object' ? file.profiles : null
+  const fileBase = fileProfiles ? fileProfiles[profile]?.baseUrl : undefined
+  const builtinBase = BUILTIN_PROFILES[profile]
+  const explicitBase = flagBase ?? envBase
+
+  if (!builtinBase && !fileBase && !explicitBase) {
+    const known = [...new Set([...Object.keys(BUILTIN_PROFILES), ...Object.keys(fileProfiles || {})])]
+    throw usageError(`未知 profile：${profile}`, `已定义的环境：${known.join(' / ')}；也可用 --base-url 或 CH_BASE_URL 直接指定 API 根地址`)
+  }
+
+  const baseUrl = String(explicitBase ?? fileBase ?? builtinBase ?? BUILTIN_PROFILES[DEFAULT_PROFILE])
+    .trim()
+    .replace(/\/+$/, '')
+
+  let baseUrlSource = 'builtin'
+  if (flagBase) baseUrlSource = 'flag'
+  else if (envBase) baseUrlSource = 'env'
+  else if (fileBase) baseUrlSource = 'config-file'
+
+  return { profile, baseUrl, baseUrlSource }
+}

package/src/errors.mjs

@@ -0,0 +1,156 @@
+/**
+ * 统一错误类型与 exit code 契约（Agent 按 exit code 分支，不需要解析中文文案）。
+ *
+ * 退出码：
+ *   0 成功
+ *   1 普通业务错误（后端 code≠200，未细分）
+ *   2 用法错误（本地校验失败：缺参数、缺 reason 等）
+ *   3 鉴权失效（HTTP 401，或 HTTP 200 + 业务码 401）：需重新 login
+ *   4 权限不足（HTTP 403，或 HTTP 200 + 业务码 403，或 ADMIN_PERMISSION_REQUIRED）
+ *   5 限流（429）：后端已限流，稍后重试
+ *   6 版本冲突且重试耗尽（VERSION_CONFLICT / GRADE_VERSION_CONFLICT）
+ *   7 网络不可达（fetch 抛错）或请求超时（NETWORK_TIMEOUT）
+ *   8 功能开关未开（FEATURE_DISABLED）
+ *   9 端点未实现（HTTP/业务 code 404 或 405）
+ */
+export const EXIT = Object.freeze({
+  OK: 0,
+  BUSINESS: 1,
+  USAGE: 2,
+  AUTH: 3,
+  PERMISSION: 4,
+  RATE_LIMIT: 5,
+  VERSION_CONFLICT: 6,
+  NETWORK: 7,
+  FEATURE_DISABLED: 8,
+  NOT_IMPLEMENTED: 9,
+})
+
+export class CliError extends Error {
+  constructor({ code, message, exitCode = EXIT.BUSINESS, reasonCode = null, httpStatus = null, payload = null, hint = null }) {
+    super(message)
+    this.name = 'CliError'
+    this.code = code
+    this.exitCode = exitCode
+    this.reasonCode = reasonCode
+    this.httpStatus = httpStatus
+    this.payload = payload
+    this.hint = hint
+  }
+
+  toJSON() {
+    const error = { code: this.code, message: this.message }
+    if (this.reasonCode) error.reasonCode = this.reasonCode
+    if (this.httpStatus !== null) error.httpStatus = this.httpStatus
+    if (this.hint) error.hint = this.hint
+    return error
+  }
+}
+
+/** 从后端错误响应体 data 中读取机器可读原因码（与 admin-web readReasonCode 同契约） */
+export function readReasonCode(payload) {
+  if (!payload || typeof payload !== 'object') return null
+  if (typeof payload.reasonCode === 'string') return payload.reasonCode
+  // 鉴权错误的历史契约字段是 data.reason（与 reasonCode 同值）
+  if (typeof payload.reason === 'string') return payload.reason
+  return null
+}
+
+export function usageError(message, hint = null) {
+  return new CliError({ code: 'USAGE_ERROR', message, exitCode: EXIT.USAGE, hint })
+}
+
+const VERSION_CONFLICT_CODES = new Set(['VERSION_CONFLICT', 'GRADE_VERSION_CONFLICT'])
+export function isVersionConflictCode(reasonCode) {
+  return typeof reasonCode === 'string' && VERSION_CONFLICT_CODES.has(reasonCode)
+}
+
+/** 登录端点：只有它的 401 才是「凭据不对」，且带 IP/账号两级限流 */
+const LOGIN_PATH = '/auth/login'
+/** 明确表示会话而非密码的原因码（JwtInterceptor 与业务端点共用这套词表） */
+const SESSION_REASON_CODES = new Set([
+  'TOKEN_EXPIRED',
+  'SESSION_EXPIRED',
+  'SESSION_ABSOLUTE_EXPIRED',
+  'AUTH_REQUIRED',
+])
+
+/**
+ * 把「非成功响应」分类成带 exit code 的 CliError。
+ * @param {{httpStatus:number, code:number, message:string, payload:unknown, retryAfter?:string|null, requestPath?:string|null}} input
+ */
+export function classifyFailure({ httpStatus, code, message, payload, retryAfter = null, requestPath = null }) {
+  const reasonCode = readReasonCode(payload)
+  const base = { reasonCode, httpStatus, payload, message }
+
+  if (httpStatus === 401) {
+    return new CliError({
+      ...base,
+      code: 'AUTH_EXPIRED',
+      exitCode: EXIT.AUTH,
+      hint: '会话已失效，请重新执行 ch login',
+    })
+  }
+  if (code === 401) {
+    // HTTP 200 + 业务码 401 在本项目有两种含义，必须分开：
+    //   /auth/login → 凭据不对（且有 IP 与账号两级限流，必须劝阻连续重试）
+    //   其它端点   → 会话没被认出来（如 InterviewAttendanceServiceImpl 的 Result.error(401,"未登录")），
+    //              此时说「账号或密码错误」会把 Agent 引向完全错误的补救方向。
+    const sessionReason = SESSION_REASON_CODES.has(reasonCode)
+    if (requestPath === LOGIN_PATH && !sessionReason) {
+      return new CliError({
+        ...base,
+        code: 'AUTH_REJECTED',
+        exitCode: EXIT.AUTH,
+        hint: '账号或密码错误；登录接口有限流（IP 60/300s、账号 10/300s），请勿连续重试',
+      })
+    }
+    return new CliError({
+      ...base,
+      code: 'AUTH_EXPIRED',
+      exitCode: EXIT.AUTH,
+      hint: '服务端未接受当前会话（原因可能是会话失效、账号停用或请求未带 Token）：先用 ch whoami 确认身份，再重新 ch login；这不是密码错误，无需改用其它凭据重试',
+    })
+  }
+  // 后端权限不足的既有契约是 HTTP 200 + body.code=403（Result.error(403, …) 是纯 POJO，
+  // 没有 @ResponseStatus，也没有 ResponseBodyAdvice 把业务码映射回 HTTP 状态；只有
+  // JwtInterceptor 与 AiCodingControllerAdvice 会真的设置 HTTP 状态）。只判 httpStatus
+  // 会让 exit 4 对绝大多数权限拒绝不可达，Agent 按文档「4 → 停止」的分支就永远走不到。
+  if (httpStatus === 403 || code === 403 || reasonCode === 'ADMIN_PERMISSION_REQUIRED') {
+    return new CliError({
+      ...base,
+      code: 'PERMISSION_DENIED',
+      exitCode: EXIT.PERMISSION,
+      hint: '当前账号权限不足；ch whoami 可查看 adminLevel 与授权组别',
+    })
+  }
+  if (httpStatus === 429 || code === 429) {
+    const hint = retryAfter ? `后端限流，请 ${retryAfter} 秒后重试` : '后端限流，请稍后重试'
+    return new CliError({ ...base, code: 'RATE_LIMITED', exitCode: EXIT.RATE_LIMIT, hint })
+  }
+  if (httpStatus === 404 || httpStatus === 405 || httpStatus === 501 || code === 404 || code === 405 || code === 501) {
+    return new CliError({
+      ...base,
+      code: 'NOT_IMPLEMENTED',
+      exitCode: EXIT.NOT_IMPLEMENTED,
+      hint: '后端未实现该接口；可检查后端版本或用 ch api 直接调用确认',
+    })
+  }
+  if (reasonCode === 'FEATURE_DISABLED') {
+    return new CliError({
+      ...base,
+      code: 'FEATURE_DISABLED',
+      exitCode: EXIT.FEATURE_DISABLED,
+      hint: '对应功能开关未开启（如 AI Coding / 三面选组 / 飞书签到）',
+    })
+  }
+  if (isVersionConflictCode(reasonCode)) {
+    return new CliError({
+      ...base,
+      code: 'VERSION_CONFLICT',
+      exitCode: EXIT.VERSION_CONFLICT,
+      hint: '数据版本已变化，请重读后使用最新 version 重试',
+    })
+  }
+  return new CliError({ ...base, code: 'BUSINESS_ERROR', exitCode: EXIT.BUSINESS })
+}