cloudhouse-admin-cli 0.3.3

package/src/argv.mjs

@@ -0,0 +1,88 @@
+/**
+ * argv 解析：位置参数 + --flag（支持 --flag=value / --flag value / --no-flag）。
+ * 重复出现的 -q / -H / -d 等多值 flag 通过 multi 取值。
+ */
+import { BOOL_FLAGS } from './flags.mjs'
+
+/** 布尔开关后面只有在跟的是布尔字面量时才把它当取值，否则 `ch --pretty dashboard` 会吃掉命令名 */
+const BOOL_LITERALS = new Set(['true', 'false', '1', '0', 'yes', 'no'])
+
+function nextIsValue(token, name) {
+  if (token === undefined || token === '-' || token.startsWith('-')) return false
+  return !BOOL_FLAGS.has(name) || BOOL_LITERALS.has(token.toLowerCase())
+}
+
+export function parseArgs(argv) {
+  const positionals = []
+  const flags = new Map()
+  const multi = new Map()
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (token === '--') {
+      positionals.push(...argv.slice(i + 1))
+      break
+    }
+    if (token.startsWith('--')) {
+      const body = token.slice(2)
+      const eq = body.indexOf('=')
+      let name = eq >= 0 ? body.slice(0, eq) : body
+      let value
+      if (eq >= 0) {
+        value = body.slice(eq + 1)
+      } else if (name.startsWith('no-')) {
+        name = name.slice(3)
+        value = false
+      } else {
+        value = nextIsValue(argv[i + 1], name) ? argv[++i] : true
+      }
+      flags.set(name, value)
+      const bucket = multi.get(name) || []
+      bucket.push(value)
+      multi.set(name, bucket)
+      continue
+    }
+    if (token.startsWith('-') && token.length > 1 && !/^-\d/.test(token)) {
+      // 单字母短选项：-q value / -q=value / -qVALUE / -q（布尔）
+      const shortMatch = token.match(/^-([A-Za-z])(?:=([\s\S]*))?$/)
+      if (shortMatch) {
+        const name = shortMatch[1]
+        let value = shortMatch[2]
+        if (value === undefined) {
+          const next = argv[i + 1]
+          if (next !== undefined && next !== '-' && !next.startsWith('-')) {
+            value = next
+            i += 1
+          } else {
+            value = true
+          }
+        }
+        flags.set(name, value)
+        const bucket = multi.get(name) || []
+        bucket.push(value)
+        multi.set(name, bucket)
+        continue
+      }
+      // 其余按布尔簇处理（如 -abc）
+      for (const ch of token.slice(1)) {
+        flags.set(ch, true)
+        const bucket = multi.get(ch) || []
+        bucket.push(true)
+        multi.set(ch, bucket)
+      }
+      continue
+    }
+    positionals.push(token)
+  }
+
+  return { positionals, flags, multi }
+}
+
+export function str(value) {
+  return typeof value === 'string' ? value : undefined
+}
+
+export function toArray(value) {
+  if (value === undefined) return []
+  return Array.isArray(value) ? value : [value]
+}

package/src/capabilities.mjs

@@ -0,0 +1,18 @@
+import { getRegistry } from './commands/index.mjs'
+import { supportedFlags, usageLines } from './flags.mjs'
+import { VERSION } from './version.mjs'
+
+export function capabilities() {
+  return { version: VERSION, schemaVersion: 1, defaultProfile: 'local', productionBaseUrl: 'https://api.dayunwu.cn/api', commands: [...getRegistry().values()].map(spec => ({
+    name: spec.name, summary: spec.summary, usage: spec.usage,
+    flags: [...supportedFlags(spec)].sort(), endpoints: spec.endpoints || [],
+    effect: spec.name === 'api' ? 'dynamic' : (spec.endpoints || []).some(e => !e.startsWith('GET ')) ? 'write' : spec.localWrite ? 'local-write' : 'read',
+    permission: spec.permission || (spec.auth === false ? 'public-or-local' : 'backend-admin-authorization'),
+    requestId: Boolean(spec.requestId), backendRequirement: spec.backendRequirement || null,
+    actions: usageLines(spec).length > 1 ? usageLines(spec).map(line => {
+      const action = line.slice(`ch ${spec.name} `.length).split(' ')[0]
+      const read = ['list', 'get', 'get-generation'].includes(action)
+      return { name: action, effect: read ? 'read' : 'write', flags: [...supportedFlags(spec, [action])].sort(), requestId: Boolean(spec.requestId && !read) }
+    }) : undefined,
+  })) }
+}

package/src/cli.mjs

@@ -0,0 +1,180 @@
+import { EXIT, CliError, usageError } from './errors.mjs'
+import { resolveConfig } from './config.mjs'
+import * as sessionStore from './session.mjs'
+import { createClient, DEFAULT_TIMEOUT_MS } from './client.mjs'
+import { printSuccess, printFailure } from './output.mjs'
+import { parseArgs } from './argv.mjs'
+import { checkFlags } from './flags.mjs'
+import { flagOn } from './payload.mjs'
+import { resolveCommand, renderHelp } from './commands/index.mjs'
+import './commands/load.mjs'
+import { VERSION } from './version.mjs'
+
+/** --timeout <ms>：1s ~ 10min，越界是用法错误而不是一个静默生效的怪值 */
+function resolveTimeoutMs(flags) {
+  const raw = flags.get('timeout')
+  if (raw === undefined) return DEFAULT_TIMEOUT_MS
+  const ms = Number(raw)
+  if (!Number.isInteger(ms) || ms < 1000 || ms > 600_000) {
+    throw usageError('--timeout 必须是 1000 到 600000 之间的整数毫秒', '默认 30000ms；注意超时不等于后端没执行')
+  }
+  return ms
+}
+
+function isOn(value) {
+  if (value === undefined) return undefined
+  if (typeof value === 'string') return !['false', '0', 'no'].includes(value.toLowerCase())
+  return value === true
+}
+
+/**
+ * `--no-pretty` 在 argv 里落成了 pretty=false，用 Map.has() 判定会把它读成「要求表格」，
+ * 于是 Agent 显式要 JSON 却拿到人类表格（JSON.parse 直接失败）。必须按取值判定真假。
+ */
+function shouldPretty(flags, stdout) {
+  const pretty = isOn(flags.get('pretty'))
+  if (pretty === true) return true
+  if (isOn(flags.get('json')) === true) return false
+  if (pretty === false) return false
+  // TTY 默认人类可读表格；管道/重定向（Agent 调用）默认 JSON
+  return Boolean(stdout && stdout.isTTY)
+}
+
+/**
+ * CLI 入口。
+ * @param {string[]} argv 不含 node 与脚本名
+ * @param {NodeJS.ProcessEnv} env
+ * @param {{stdout?:NodeJS.WritableStream, stderr?:NodeJS.WritableStream}} io
+ * @returns {Promise<number>} exit code
+ */
+export async function run(argv, env = process.env, io = {}) {
+  const stdout = io.stdout || process.stdout
+  const stderr = io.stderr || process.stderr
+  const { positionals, flags, multi } = parseArgs(argv)
+  const pretty = shouldPretty(flags, stdout)
+
+  try {
+    if ((positionals.length === 0 && flags.get('version') === true) || (positionals.length === 1 && positionals[0] === 'version')) {
+      printSuccess(stdout, { name: 'cloudhouse-admin-cli', version: VERSION }, { pretty })
+      return EXIT.OK
+    }
+    // `ch candidates list --help` 的目标就是 positionals 本身；早先无条件 slice(1)
+    // 会把命令词切掉，只剩 ['list'] → 打印「未找到命令：list」还 return 0。
+    const helpRequested = flags.get('help') !== undefined && flags.get('help') !== false
+    if (helpRequested || positionals.length === 0 || positionals[0] === 'help') {
+      const target = helpRequested ? positionals : positionals[0] === 'help' ? positionals.slice(1) : []
+      const help = renderHelp(target)
+      stdout.write(`${help.text}\n`)
+      if (help.missing) {
+        throw usageError(`未找到命令：${target.join(' ')}`, '运行 ch help 查看全部命令')
+      }
+      return EXIT.OK
+    }
+
+    const globals = {
+      pretty,
+      profile: typeof flags.get('profile') === 'string' ? flags.get('profile') : undefined,
+      baseUrl: typeof flags.get('base-url') === 'string' ? flags.get('base-url') : undefined,
+    }
+    const command = resolveCommand(positionals)
+    if (!command) {
+      throw usageError(`未知命令：${positionals.join(' ')}`, '运行 ch help 查看全部命令')
+    }
+    const { key, spec, args } = command
+    // 只有 backend/aicoding 读 body.requestId 并做去重，其它端点的审计 requestId 由服务端
+    // 自己生成（AdminInterviewAuditContext）。过去非 AI 命令把它静默丢弃，而文档承诺
+    // 「所有写操作幂等」，Agent 照文档重放超时/5xx 的写就会重复录入——静默接受比报错更危险。
+    if (flags.get('request-id') !== undefined && spec.requestId !== true) {
+      throw usageError(
+        '--request-id 只被 ch ai * 的写操作支持',
+        '其余端点不读取该字段，重放保护请依赖幂等的读接口或在应用层去重；直接去掉 --request-id 即可执行',
+      )
+    }
+    for (const warning of checkFlags({ entries: [...flags.entries()], spec, positionals: args })) {
+      stderr.write(`警告：${warning}\n`)
+    }
+    const config = resolveConfig({ flags: globals, env })
+
+    const savedSession = spec.auth === false ? null : sessionStore.loadSession(env)
+    const envToken = typeof env.CH_TOKEN === 'string' ? env.CH_TOKEN.trim() : ''
+    let token = envToken || (savedSession && savedSession.token) || null
+
+    // 「会话文件坏了」和「从没登录过」的处置方式完全不同：前者修文件，后者只需要 login。
+    // 过去两者都报 NOT_LOGGED_IN，用户反复登录也反复被同一个坏文件挡住。
+    if (!token && spec.auth !== false) {
+      const damage = sessionStore.describeSessionDamage(env)
+      if (damage) {
+        throw new CliError({
+          code: 'SESSION_DAMAGED',
+          message: `本地会话文件不可用：${damage.file}（${damage.reason}）`,
+          exitCode: EXIT.AUTH,
+          hint: '确认没有其它凭据来源后可删除该文件再执行 ch login；删除会丢弃当前会话',
+        })
+      }
+    }
+    // 会话只有一份 session.json，不按 profile 分文件：`ch login --profile prod` 之后
+    // 裸跑命令会默认 local，把生产 token 发到本地（或反过来）。这里比对登录时记录的
+    // baseUrl，不一致默认拒绝；--allow-profile-mismatch 用于确实要跨环境的场景。
+    if (!envToken && token && savedSession && typeof savedSession.baseUrl === 'string' && savedSession.baseUrl !== config.baseUrl) {
+      if (flagOn({ flags }, 'allow-profile-mismatch')) {
+        stderr.write(`提示：已用 --allow-profile-mismatch 放行跨环境会话。\n`)
+      } else {
+        throw usageError(`本地会话来自 ${savedSession.baseUrl}，目标为 ${config.baseUrl}；已阻止跨环境发送 Bearer Token`, '重新登录目标环境，或确认后显式加 --allow-profile-mismatch')
+      }
+    }
+
+    const client = createClient({
+      baseUrl: config.baseUrl,
+      timeoutMs: resolveTimeoutMs(flags),
+      // 未登录延迟到真正要发请求时才判定：命令体的本地参数校验在此之前完成，
+      // 用法错误（2）才不会被鉴权错误（3）掩盖——否则 `ch candidates list --page abc`
+      // 在未登录时永远只报「请先登录」，调用方看不到 --page 才是错的。
+      getAuthHeaders: () => {
+        if (!token) {
+          throw new CliError({
+            code: 'NOT_LOGGED_IN',
+            message: '尚未登录：未找到本地会话（~/.config/cloudhouse-cli/session.json）且未设置 CH_TOKEN',
+            exitCode: EXIT.AUTH,
+            hint: '先执行 ch login，或为 Agent 场景设置 CH_TOKEN 环境变量',
+          })
+        }
+        return { Authorization: `Bearer ${token}` }
+      },
+      onRenewal: (sentToken, renewedToken, expiresAt) => {
+        if (token === sentToken) token = renewedToken
+        try {
+          sessionStore.absorbRenewal(env, sentToken, renewedToken, expiresAt)
+        } catch {
+          /* 续期落盘失败不阻断命令；下次仍可用旧 token 直至绝对上限 */
+        }
+      },
+    })
+
+    const ctx = {
+      key,
+      client,
+      config,
+      flags,
+      multi,
+      positionals: args,
+      pretty,
+      env,
+      session: savedSession,
+      token,
+      stdout,
+      stderr,
+      log: (message) => stderr.write(`${message}\n`),
+      setToken: (next) => {
+        token = next
+      },
+    }
+
+    const data = await spec.run(ctx)
+    printSuccess(stdout, data, { pretty })
+    return EXIT.OK
+  } catch (err) {
+    printFailure(stdout, stderr, err)
+    if (err instanceof CliError) return err.exitCode
+    return EXIT.BUSINESS
+  }
+}

package/src/client.mjs

@@ -0,0 +1,169 @@
+import { CliError, classifyFailure, usageError, EXIT } from './errors.mjs'
+
+const RENEWED_TOKEN_HEADER = 'X-Renewed-Token'
+const TOKEN_EXPIRES_AT_HEADER = 'X-Token-Expires-At'
+
+/**
+ * 没有超时的 fetch 会让 CLI 永久阻塞，对 Agent 流水线是致命的：它无法按退出码分支，
+ * 只能被上层 kill 掉。普通请求 30s，multipart 上传放宽到 120s（大附件本来就慢）。
+ */
+export const DEFAULT_TIMEOUT_MS = 30_000
+export const UPLOAD_TIMEOUT_MS = 120_000
+
+/**
+ * 封装与后端的全部 HTTP 交互。
+ *
+ * @param {object} options
+ * @param {string} options.baseUrl API 根地址（不含路径），如 http://127.0.0.1:8080/api
+ * @param {() => Record<string,string>} options.getAuthHeaders 每次请求时取当前鉴权头（支持续期后换 token）
+ * @param {(sentToken:string, renewedToken:string, expiresAtMs:number|null) => void} [options.onRenewal]
+ */
+export function createClient({ baseUrl, getAuthHeaders, onRenewal, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  /**
+   * 路径形状守门：位置参数是裸插值进 path 模板的，`ch candidates get "42?foo=bar"`
+   * 实测发出 /users/42?foo=bar/info——new URL() 把尾随的 /info 当成了查询串的值，
+   * 请求被静默改形还照旧带上 JWT 打向真实端点。空格 / # \ 与 `..` 同理。
+   * 只有 `ch api` 允许在路径里直接写查询串（它就是逃生舱）。
+   */
+  function buildUrl(requestPath, query, { allowQuery = false } = {}) {
+    if (typeof requestPath !== 'string' || !requestPath.startsWith('/')) {
+      throw new CliError({
+        code: 'INVALID_PATH',
+        message: `接口路径必须以 / 开头：${requestPath}`,
+        exitCode: EXIT.USAGE,
+      })
+    }
+    const [pathPart, ...rest] = requestPath.split('?')
+    if (rest.length > 0 && !allowQuery) {
+      throw usageError(`接口路径里不能带查询串：${requestPath}`, '查询参数请用 -q k=v（ch api）或对应的语义 flag')
+    }
+    if (/[#\s]|\.\./.test(pathPart)) {
+      throw usageError(`接口路径含未编码的字符：${requestPath}`, '路径参数中的空格、# 与 .. 会改变请求形状；数字 id 请直接给数字')
+    }
+    const url = new URL(`${baseUrl.replace(/\/+$/, '')}${requestPath}`)
+    if (query) {
+      for (const [key, value] of query) {
+        if (value !== undefined && value !== null && value !== '') url.searchParams.append(key, String(value))
+      }
+    }
+    return url.toString()
+  }
+
+  function absorbRenewal(response, authHeader) {
+    if (!onRenewal || !authHeader) return
+    const sentToken = authHeader.replace(/^Bearer\s+/i, '')
+    const renewed = response.headers.get(RENEWED_TOKEN_HEADER)
+    if (!renewed || renewed === sentToken) return
+    const rawExpires = response.headers.get(TOKEN_EXPIRES_AT_HEADER)
+    const expiresAt = rawExpires !== null && Number.isFinite(Number(rawExpires)) ? Number(rawExpires) : null
+    onRenewal(sentToken, renewed, expiresAt)
+  }
+
+  /**
+   * 发起一次请求。
+   * @param {object} request
+   * @param {'GET'|'POST'|'PUT'|'PATCH'|'DELETE'} [request.method]
+   * @param {string} request.path 以 / 开头
+   * @param {Array<[string, string|number]>} [request.query] 查询参数
+   * @param {unknown} [request.body] 普通 JSON 载荷
+   * @param {FormData} [request.formData] multipart 载荷（与 body 互斥）
+   * @param {Record<string,string>} [request.headers] 额外请求头
+   * @param {boolean} [request.noAuth] 公开端点：不携带 Authorization
+   * @param {boolean} [request.raw] 二进制响应模式：返回 Buffer 而非解析 JSON
+   * @param {boolean} [request.allowQuery] 允许 path 里直接写查询串（仅 ch api）
+   * @returns {Promise<{httpStatus:number, data:unknown}>}
+   */
+  async function request({ method = 'GET', path: requestPath, query, body, formData, headers = {}, noAuth = false, raw = false, allowQuery = false }) {
+    const authHeaders = noAuth ? {} : getAuthHeaders()
+    const url = buildUrl(requestPath, query, { allowQuery })
+
+    const requestHeaders = { Accept: 'application/json', ...authHeaders, ...headers }
+    let payload
+    if (formData !== undefined) {
+      payload = formData
+    } else if (body !== undefined) {
+      requestHeaders['Content-Type'] = 'application/json'
+      payload = JSON.stringify(body)
+    }
+
+    let response
+    const limit = formData !== undefined ? Math.max(timeoutMs, UPLOAD_TIMEOUT_MS) : timeoutMs
+    try {
+      response = await fetch(url, { method, headers: requestHeaders, body: payload, signal: AbortSignal.timeout(limit), redirect: 'error' })
+    } catch (err) {
+      const timedOut = err && (err.name === 'TimeoutError' || err.name === 'AbortError')
+      if (timedOut) {
+        throw new CliError({
+          code: 'NETWORK_TIMEOUT',
+          message: `请求超时（${limit}ms）：${method} ${url}`,
+          exitCode: EXIT.NETWORK,
+          hint: '超时不等于没执行：写操作可能已经在后端生效。先用读接口确认结果，不要直接重放；确需放宽用 --timeout <ms>',
+        })
+      }
+      throw new CliError({
+        code: 'NETWORK_UNREACHABLE',
+        message: `无法连接后端服务（${url}）：${err && err.message ? err.message : err}`,
+        exitCode: EXIT.NETWORK,
+        hint: '请检查 baseUrl（--base-url / CH_BASE_URL / ch profile）、网络与后端进程',
+      })
+    }
+
+    absorbRenewal(response, requestHeaders.Authorization)
+
+    let envelope = null
+    const binary = raw ? Buffer.from(await response.arrayBuffer()) : null
+    const rawJson = raw && /(?:application\/json|\+json)/i.test(response.headers.get('Content-Type') || '')
+    if (!raw || rawJson) {
+      const text = raw ? binary.toString('utf8') : await response.text()
+      if (text) {
+        try {
+          envelope = JSON.parse(text)
+        } catch {
+          envelope = null
+        }
+      }
+    }
+
+    const envelopeCode = envelope && typeof envelope.code === 'number' ? envelope.code : null
+    if (response.ok && !raw && response.status !== 204 && (envelopeCode === null || !envelope || Array.isArray(envelope))) {
+      throw new CliError({ code: 'UNEXPECTED_RESPONSE', message: `接口返回无效 JSON 信封（HTTP ${response.status}）`, exitCode: EXIT.BUSINESS, hint: '检查 API 根地址和代理路由；这不是成功响应，写操作结果未知时先查询确认' })
+    }
+    if (response.ok && raw && (/text\/html/i.test(response.headers.get('Content-Type') || '') || rawJson && (envelopeCode === null || envelopeCode === 200))) {
+      throw new CliError({ code: 'UNEXPECTED_RESPONSE', message: '附件接口返回 HTML 或 JSON，未保存文件', exitCode: EXIT.BUSINESS })
+    }
+    if (response.ok && (envelopeCode === null || envelopeCode === 200)) {
+      if (raw) {
+        return {
+          httpStatus: response.status,
+          contentType: response.headers.get('Content-Type'),
+          contentDisposition: response.headers.get('Content-Disposition'),
+          buffer: binary,
+        }
+      }
+      return { httpStatus: response.status, data: envelope ? (envelope.data ?? null) : null }
+    }
+
+    // 反向代理/网关异常时可能返回 HTML：统一转成结构化错误
+    if (!envelope) {
+      throw classifyFailure({
+        httpStatus: response.status,
+        code: response.status,
+        message: `请求失败（HTTP ${response.status}，非 JSON 响应）`,
+        payload: null,
+        retryAfter: response.headers.get('Retry-After'),
+        requestPath,
+      })
+    }
+
+    throw classifyFailure({
+      httpStatus: response.status,
+      code: envelopeCode ?? response.status,
+      message: typeof envelope.message === 'string' && envelope.message ? envelope.message : `请求失败（HTTP ${response.status}）`,
+      payload: envelope.data ?? null,
+      retryAfter: response.headers.get('Retry-After'),
+      requestPath,
+    })
+  }
+
+  return { request, get baseUrl() { return baseUrl.replace(/\/+$/, '') } }
+}

package/src/commands/accounts.mjs

@@ -0,0 +1,115 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { flagEnum, flagString, flagNumber, payloadFrom, parseIdList } from '../payload.mjs'
+import { idParam } from '../path.mjs'
+
+const ADMIN_LEVELS = ['SUPER', 'REGULAR', 'INTERVIEWER']
+
+function validateStudentNo(studentNo) {
+  if (!/^\d{10}$/.test(studentNo)) {
+    throw usageError('学号必须是 10 位数字', '与招新系统学号规则一致')
+  }
+}
+
+function validatePassword(password) {
+  if (typeof password !== 'string' || password.length < 6) {
+    throw usageError('密码长度不能少于 6 位')
+  }
+}
+
+register('accounts list', {
+  summary: '管理员账号列表',
+  usage: 'ch accounts list [--pretty]',
+  endpoints: ['GET /admin/accounts'],
+  run: async (ctx) => {
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/accounts' })
+    return data
+  },
+})
+
+register('accounts create', {
+  summary: '创建分级管理员账号',
+  usage: 'ch accounts create --studentNo 10位学号 --password 密码 [--real-name 姓名] --admin-level SUPER|REGULAR|INTERVIEWER [--authorized-group-ids 1,2]',
+  endpoints: ['POST /admin/accounts'],
+  run: async (ctx) => {
+    const studentNo = flagString(ctx, 'studentNo', { required: true, label: 'ch accounts create --studentNo 2026000001' })
+    validateStudentNo(studentNo)
+    const password = flagString(ctx, 'password', { required: true, label: 'ch accounts create --password ******' })
+    validatePassword(password)
+    const adminLevel = flagEnum(ctx, 'admin-level', ADMIN_LEVELS, { required: true, label: `--admin-level ${ADMIN_LEVELS.join('|')}` })
+    const base = { studentNo, password, adminLevel }
+    const realName = flagString(ctx, 'real-name')
+    if (realName !== undefined) base.realName = realName
+    const groupIds = flagString(ctx, 'authorized-group-ids')
+    if (groupIds !== undefined) base.authorizedGroupIds = parseIdList(groupIds, { flag: 'authorized-group-ids' })
+    const payload = payloadFrom(ctx, base)
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/accounts', body: payload })
+    return data
+  },
+})
+
+register('accounts batch', {
+  summary: '批量创建同级别管理员账号',
+  usage: 'ch accounts batch --count N --password 初始密码 --admin-level SUPER|REGULAR|INTERVIEWER [--authorized-group-ids 1,2]',
+  endpoints: ['POST /admin/accounts/batch'],
+  run: async (ctx) => {
+    const count = flagNumber(ctx, 'count', { required: true, label: 'ch accounts batch --count 5' })
+    if (!Number.isInteger(count) || count <= 0) throw usageError('--count 必须是正整数')
+    const password = flagString(ctx, 'password', { required: true, label: 'ch accounts batch --password ******' })
+    validatePassword(password)
+    const adminLevel = flagEnum(ctx, 'admin-level', ADMIN_LEVELS, { required: true, label: `--admin-level ${ADMIN_LEVELS.join('|')}` })
+    const base = { count, password, adminLevel }
+    const groupIds = flagString(ctx, 'authorized-group-ids')
+    if (groupIds !== undefined) base.authorizedGroupIds = parseIdList(groupIds, { flag: 'authorized-group-ids' })
+    const payload = payloadFrom(ctx, base)
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/accounts/batch', body: payload })
+    return data
+  },
+})
+
+register('accounts update', {
+  summary: '修改管理员资料/级别/授权组别',
+  usage: 'ch accounts update <id> [--real-name 姓名] [--admin-level SUPER|REGULAR|INTERVIEWER] [--authorized-group-ids 1,2]',
+  endpoints: ['PUT /admin/accounts/{id}'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '管理员 id' })
+    const base = {}
+    const realName = flagString(ctx, 'real-name')
+    if (realName !== undefined) base.realName = realName
+    const adminLevel = flagEnum(ctx, 'admin-level', ADMIN_LEVELS)
+    if (adminLevel !== undefined) base.adminLevel = adminLevel
+    const groupIds = flagString(ctx, 'authorized-group-ids')
+    if (groupIds !== undefined) base.authorizedGroupIds = parseIdList(groupIds, { flag: 'authorized-group-ids' })
+    const payload = payloadFrom(ctx, base)
+    if (Object.keys(payload).length === 0) {
+      throw usageError('至少提供一个修改字段', '--real-name / --admin-level / --authorized-group-ids')
+    }
+    const { data } = await ctx.client.request({ method: 'PUT', path: `/admin/accounts/${id}`, body: payload })
+    return data
+  },
+})
+
+register('accounts reset-password', {
+  summary: '重置管理员密码',
+  usage: 'ch accounts reset-password <id> --password 新密码',
+  endpoints: ['PUT /admin/accounts/{id}/password'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '管理员 id' })
+    const password = flagString(ctx, 'password', { required: true, label: 'ch accounts reset-password <id> --password ******' })
+    validatePassword(password)
+    const payload = payloadFrom(ctx, { password })
+    const { data } = await ctx.client.request({ method: 'PUT', path: `/admin/accounts/${id}/password`, body: payload })
+    return data === null ? { reset: true, id: Number(id) } : data
+  },
+})
+
+register('accounts delete', {
+  summary: '删除管理员账号（初始管理员与自身由后端拒绝）',
+  usage: 'ch accounts delete <id>',
+  endpoints: ['DELETE /admin/accounts/{id}'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '管理员 id' })
+    const { data } = await ctx.client.request({ method: 'DELETE', path: `/admin/accounts/${id}` })
+    return data === null ? { deleted: true, id: Number(id) } : data
+  },
+})

package/src/commands/agent.mjs

@@ -0,0 +1,13 @@
+import { register } from './index.mjs'
+import { capabilities } from '../capabilities.mjs'
+import { installAgent } from '../agent-install.mjs'
+import { flagString } from '../payload.mjs'
+import { usageError } from '../errors.mjs'
+register('capabilities', { summary: '离线机器可读能力目录（含参数、读写、权限、幂等与后端要求）', usage: 'ch capabilities [--json]', auth: false, endpoints: [], run: async () => capabilities() })
+register('agent install', {
+  summary: '为 agent 安装原生技能/插件（仅本地，不含凭据）', usage: 'ch agent install <agent> [--scope user|project]', auth: false, localWrite: true, endpoints: [],
+  run: async ctx => {
+    if (ctx.positionals.length !== 1) throw usageError('用法：ch agent install <codex|dsh|opencode|openclaw|pi> --scope user|project')
+    return installAgent(ctx.positionals[0], flagString(ctx, 'scope') || 'user', ctx.env)
+  },
+})