cloudhouse-admin-cli 0.3.3

package/src/commands/ai.mjs

@@ -0,0 +1,420 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { collectQuery, parseNumber } from '../query.mjs'
+import { flagEnum, flagString, flagNumber, flagBool, payloadFrom, camelCase } from '../payload.mjs'
+import { requireReason } from '../sensitive.mjs'
+import { runWithVersionRetry, newRequestId } from '../idempotent.mjs'
+import { toShanghaiOffset } from '../time.mjs'
+import { idParam, textParam } from '../path.mjs'
+
+/** planInputFromFlags 的 flag 清单：常量声明，flag 词表守护测试才扫得到内联字面量以外的名字 */
+const PLAN_TIME_FLAGS = ['opens-at', 'closes-at', 'publish-at']
+const DURATION_FLAGS = ['survey-seconds', 'coding-seconds', 'reflection-seconds']
+
+/**
+ * requestId 优先级：重试下发的新 id > --request-id > -d 里的 requestId > 新生成。
+ * 「重试下发的 id」排第一是有意的：runWithVersionRetry 只在自动重试时给出取值，
+ * 首次请求给 null，此时才轮到显式 --request-id。若把显式 id 放在最前，版本冲突重试
+ * 会复用同一个 id，而重试 body 里的 version 已经变了——后端 replay() 判定
+ * 「同 requestId + 不同 body」直接抛 IDEMPOTENCY_CONFLICT，自动重试于是永远失败。
+ * 早先的 `{ requestId: ..., ...base }` 还会让 -d 反向盖掉 --request-id。
+ * 带自动重试的写命令由 runWithVersionRetry 统一签发 id，因此 -d 里写 requestId
+ * 在这些命令上不再生效——幂等只保留一个来源，比「看哪个 flag 后写」更可预测。
+ * @param {object} ctx
+ * @param {object} base
+ * @param {string|null} [issued] runWithVersionRetry 下发的 id（仅重试时非空）
+ */
+function withRequestId(ctx, base, issued = null) {
+  const explicit = flagString(ctx, 'request-id')
+  return { ...base, requestId: issued || explicit || base.requestId || newRequestId() }
+}
+
+/** 列表查询参数（page/pageSize + 各资源特有筛选） */
+function listQuery(ctx, extra = {}) {
+  const query = collectQuery(ctx, { page: { parse: parseNumber }, 'page-size': { key: 'pageSize', parse: parseNumber }, ...extra })
+  return query
+}
+
+/**
+ * AI Coding 的 groupIds 必须保持「字符串数组」：后端 AiCodingValidation.ids()
+ * 对非 textual 元素直接 400，再逐个 Long.parseLong。
+ * 但原来的 `.filter(Boolean)` 会把空段静默丢掉（`1,,3` 变成两个），改成显式拒绝。
+ */
+function parseGroupIds(raw) {
+  return String(raw).split(',').map((part) => {
+    const text = part.trim()
+    if (!/^[1-9]\d*$/.test(text)) {
+      throw usageError(`--group-ids 含无效 id：${text === '' ? '（空段）' : text}`, '用逗号分隔的正整数，如 --group-ids 1,2,3；不要留空段或尾随逗号')
+    }
+    return text
+  })
+}
+
+/* ============================ ai plans ============================ */
+
+const PLAN_ACTIONS = new Set(['list', 'get', 'create', 'update', 'publish', 'withdraw', 'starts', 'publication', 'credential'])
+
+function planInputFromFlags(ctx) {
+  const base = {}
+  const name = flagString(ctx, 'name', { required: true, label: 'ch ai plans create --name 计划名' })
+  base.name = name
+  const groupIds = flagString(ctx, 'group-ids', { required: true, label: '--group-ids 1,2' })
+  base.groupIds = parseGroupIds(groupIds)
+  for (const flag of PLAN_TIME_FLAGS) {
+    const value = flagString(ctx, flag)
+    base[camelCase(flag)] = value === undefined ? null : toShanghaiOffset(value)
+  }
+  const reflectionMode = flagEnum(ctx, 'reflection-mode', ['STATIC', 'PERSONALIZED'])
+  if (reflectionMode !== undefined) base.reflectionMode = reflectionMode
+  const durations = {}
+  for (const flag of DURATION_FLAGS) {
+    const value = flagNumber(ctx, flag)
+    if (value !== undefined) durations[camelCase(flag)] = value
+  }
+  if (Object.keys(durations).length > 0) base.durations = durations
+  return payloadFrom(ctx, base)
+}
+
+register('ai plans', {
+  summary: 'AI Coding 计划：list/get/create/update/publish/withdraw/starts/publication/credential',
+  // 只有 AI Coding 端点读 body.requestId 并去重，因此 --request-id 仅在这些命令上有意义
+  requestId: true,
+  usage: [
+    'ch ai plans list [--page N] [--page-size N] [--status DRAFT|PUBLISHED] [--group-id N]',
+    'ch ai plans get <id>',
+    'ch ai plans create --name 名 --group-ids 1,2 [--opens-at "..."] [--closes-at "..."] [--publish-at "..."] [--survey-seconds N] [--coding-seconds N] [--reflection-seconds N] [--reflection-mode STATIC|PERSONALIZED] [-d @plan.json]',
+    'ch ai plans update <id> [...同 create...] [--version N]   # version 缺省自动重读',
+    'ch ai plans publish <id>',
+    'ch ai plans withdraw <id> --reason 原因',
+    'ch ai plans starts <id> --paused true|false --reason 原因',
+    'ch ai plans publication <id> --publish-at "..." --reason 原因',
+    'ch ai plans credential <id> <modelId> --api-key sk-... --reason 原因',
+  ].join('\n  '),
+  endpoints: [
+    'GET /admin/ai-coding/plans',
+    'POST /admin/ai-coding/plans',
+    'GET /admin/ai-coding/plans/{id}',
+    'PUT /admin/ai-coding/plans/{id}',
+    'POST /admin/ai-coding/plans/{id}/publish',
+    'POST /admin/ai-coding/plans/{id}/withdraw',
+    'PATCH /admin/ai-coding/plans/{id}/starts',
+    'PATCH /admin/ai-coding/plans/{id}/publication',
+    'PUT /admin/ai-coding/plans/{id}/models/{modelId}/credential',
+  ],
+  run: async (ctx) => {
+    const [action, ...rest] = ctx.positionals
+    if (!PLAN_ACTIONS.has(action)) {
+      throw usageError(`ai plans 子命令必须是 ${[...PLAN_ACTIONS].join('|')}`, '用法：ch help ai plans')
+    }
+    const id = textParam(rest[0], { label: 'id', allowEmpty: true })
+
+    if (action === 'list') {
+      const { data } = await ctx.client.request({
+        method: 'GET',
+        path: '/admin/ai-coding/plans',
+        query: listQuery(ctx, { status: { key: 'status' }, 'group-id': { key: 'groupId' } }),
+      })
+      return data
+    }
+    if (action === 'get') {
+      if (!id) throw usageError('缺少计划 id', '用法：ch ai plans get <id>')
+      const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/plans/${id}` })
+      return data
+    }
+    if (action === 'create') {
+      const input = planInputFromFlags(ctx)
+      const { data } = await ctx.client.request({
+        method: 'POST',
+        path: '/admin/ai-coding/plans',
+        body: withRequestId(ctx, input),
+      })
+      return data
+    }
+    if (action === 'update') {
+      if (!id) throw usageError('缺少计划 id', '用法：ch ai plans update <id>')
+      const input = planInputFromFlags(ctx)
+      return runWithVersionRetry({
+        explicitVersion: flagNumber(ctx, 'version'),
+        explicitRequestId: flagString(ctx, 'request-id'),
+        readVersion: async () => {
+          const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/plans/${id}` })
+          if (typeof data?.version !== 'number') throw usageError('计划详情中没有 version')
+          return data.version
+        },
+        log: (m) => ctx.log(m),
+        run: async ({ requestId, version }) => {
+          const { data } = await ctx.client.request({
+            method: 'PUT',
+            path: `/admin/ai-coding/plans/${id}`,
+            body: withRequestId(ctx, { ...input, version }, requestId),
+          })
+          return data
+        },
+      })
+    }
+    if (action === 'publish') {
+      if (!id) throw usageError('缺少计划 id', '用法：ch ai plans publish <id>')
+      return runWithVersionRetry({
+        explicitVersion: flagNumber(ctx, 'version'),
+        explicitRequestId: flagString(ctx, 'request-id'),
+        readVersion: async () => {
+          const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/plans/${id}` })
+          if (typeof data?.version !== 'number') throw usageError('计划详情中没有 version')
+          return data.version
+        },
+        log: (m) => ctx.log(m),
+        run: async ({ requestId, version }) => {
+          const { data } = await ctx.client.request({
+            method: 'POST',
+            path: `/admin/ai-coding/plans/${id}/publish`,
+            body: withRequestId(ctx, { version }, requestId),
+          })
+          return data
+        },
+      })
+    }
+    if (action === 'withdraw') {
+      if (!id) throw usageError('缺少计划 id', '用法：ch ai plans withdraw <id> --reason 原因')
+      const reason = requireReason(ctx, { label: 'ch ai plans withdraw <id> --reason 原因' })
+      return runWithVersionRetry({
+        explicitVersion: flagNumber(ctx, 'version'),
+        explicitRequestId: flagString(ctx, 'request-id'),
+        readVersion: async () => {
+          const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/plans/${id}` })
+          if (typeof data?.version !== 'number') throw usageError('计划详情中没有 version')
+          return data.version
+        },
+        log: (m) => ctx.log(m),
+        run: async ({ requestId, version }) => {
+          const { data } = await ctx.client.request({
+            method: 'POST',
+            path: `/admin/ai-coding/plans/${id}/withdraw`,
+            body: withRequestId(ctx, { version, reason }, requestId),
+          })
+          return data
+        },
+      })
+    }
+    if (action === 'starts') {
+      if (!id) throw usageError('缺少计划 id', '用法：ch ai plans starts <id> --paused true --reason 原因')
+      const paused = flagBool(ctx, 'paused')
+      if (paused === undefined) throw usageError('缺少 --paused', '用法：ch ai plans starts <id> --paused true|false --reason 原因')
+      const reason = requireReason(ctx, { label: '--reason 原因' })
+      return runWithVersionRetry({
+        explicitVersion: flagNumber(ctx, 'version'),
+        explicitRequestId: flagString(ctx, 'request-id'),
+        readVersion: async () => {
+          const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/plans/${id}` })
+          if (typeof data?.version !== 'number') throw usageError('计划详情中没有 version')
+          return data.version
+        },
+        log: (m) => ctx.log(m),
+        run: async ({ requestId, version }) => {
+          const { data } = await ctx.client.request({
+            method: 'PATCH',
+            path: `/admin/ai-coding/plans/${id}/starts`,
+            body: withRequestId(ctx, { version, paused, reason }, requestId),
+          })
+          return data
+        },
+      })
+    }
+    if (action === 'publication') {
+      if (!id) throw usageError('缺少计划 id', '用法：ch ai plans publication <id> --publish-at "..." --reason 原因')
+      const publishAt = flagString(ctx, 'publish-at', { required: true, label: '--publish-at "2026-09-29 09:00"' })
+      const reason = requireReason(ctx, { label: '--reason 原因' })
+      return runWithVersionRetry({
+        explicitVersion: flagNumber(ctx, 'version'),
+        explicitRequestId: flagString(ctx, 'request-id'),
+        readVersion: async () => {
+          const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/plans/${id}` })
+          if (typeof data?.version !== 'number') throw usageError('计划详情中没有 version')
+          return data.version
+        },
+        log: (m) => ctx.log(m),
+        run: async ({ requestId, version }) => {
+          const { data } = await ctx.client.request({
+            method: 'PATCH',
+            path: `/admin/ai-coding/plans/${id}/publication`,
+            body: withRequestId(ctx, { version, publishAt: toShanghaiOffset(publishAt), reason }, requestId),
+          })
+          return data
+        },
+      })
+    }
+    // action === 'credential'
+    const modelId = rest[1]
+    if (!modelId) throw usageError('缺少 modelId', '用法：ch ai plans credential <id> <modelId> --api-key sk-... --reason 原因')
+    const apiKey = flagString(ctx, 'api-key', { required: true, label: '--api-key sk-...' })
+    const reason = requireReason(ctx, { label: '--reason 轮换原因' })
+    return runWithVersionRetry({
+      explicitVersion: flagNumber(ctx, 'key-version'),
+      explicitRequestId: flagString(ctx, 'request-id'),
+      readVersion: async () => {
+        const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/plans/${id}` })
+        const model = Array.isArray(data?.models) ? data.models.find((m) => String(m.id) === String(modelId)) : null
+        if (!model || typeof model.keyVersion !== 'number') {
+          throw usageError(`计划 ${id} 中找不到模型 ${modelId} 的 keyVersion，可用 --key-version 显式指定`)
+        }
+        return model.keyVersion
+      },
+      log: (m) => ctx.log(m),
+      run: async ({ requestId, version }) => {
+        const { data } = await ctx.client.request({
+          method: 'PUT',
+          path: `/admin/ai-coding/plans/${id}/models/${textParam(modelId, { label: 'modelId' })}/credential`,
+          body: withRequestId(ctx, { keyVersion: version, apiKey, reason }, requestId),
+        })
+        return data
+      },
+    })
+  },
+})
+
+/* ============================ ai attempts ============================ */
+
+const ATTEMPT_ACTIONS = new Set(['list', 'get', 'grade', 'void'])
+
+register('ai attempts', {
+  summary: 'AI Coding 考次：list/get/grade/void',
+  requestId: true,
+  usage: [
+    'ch ai attempts list [--page N] [--page-size N] [--plan-id N] [--group-id N] [--state SURVEY|CODING|REFLECTION|SUBMITTED|VOIDED] [--grade-state UNGRADED|HIDDEN|PUBLISHED|VOIDED] [--keyword 关键词]',
+    'ch ai attempts get <id>',
+    'ch ai attempts grade <id> --score 85 --public-comment 公开评价 --internal-comment 内部评价 [--reason 修正原因]',
+    'ch ai attempts void <id> --reason 原因',
+  ].join('\n  '),
+  endpoints: [
+    'GET /admin/ai-coding/attempts',
+    'GET /admin/ai-coding/attempts/{id}',
+    'PUT /admin/ai-coding/attempts/{id}/grade',
+    'POST /admin/ai-coding/attempts/{id}/void',
+  ],
+  run: async (ctx) => {
+    const [action, ...rest] = ctx.positionals
+    if (!ATTEMPT_ACTIONS.has(action)) {
+      throw usageError(`ai attempts 子命令必须是 ${[...ATTEMPT_ACTIONS].join('|')}`, '用法：ch help ai attempts')
+    }
+    const id = textParam(rest[0], { label: 'id', allowEmpty: true })
+
+    if (action === 'list') {
+      const { data } = await ctx.client.request({
+        method: 'GET',
+        path: '/admin/ai-coding/attempts',
+        query: listQuery(ctx, {
+          'plan-id': { key: 'planId' },
+          'group-id': { key: 'groupId' },
+          state: { key: 'state' },
+          'grade-state': { key: 'gradeState' },
+          keyword: { key: 'keyword' },
+        }),
+      })
+      return data
+    }
+    if (action === 'get') {
+      if (!id) throw usageError('缺少考次 id', '用法：ch ai attempts get <id>')
+      const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/attempts/${id}` })
+      return data
+    }
+    if (action === 'grade') {
+      if (!id) throw usageError('缺少考次 id', '用法：ch ai attempts grade <id> --score 85 --public-comment ...')
+      const score = flagNumber(ctx, 'score', { required: true, label: '--score 0-100 整数' })
+      if (!Number.isInteger(score) || score < 0 || score > 100) throw usageError('--score 必须是 0-100 的整数')
+      const publicComment = flagString(ctx, 'public-comment', { required: true, label: '--public-comment 考生可见评价' })
+      const internalComment = flagString(ctx, 'internal-comment', { required: true, label: '--internal-comment 内部评价' })
+      const reason = flagString(ctx, 'reason')
+      return runWithVersionRetry({
+        explicitVersion: flagNumber(ctx, 'expected-revision'),
+        explicitRequestId: flagString(ctx, 'request-id'),
+        readVersion: async () => {
+          const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/attempts/${id}` })
+          if (typeof data?.attempt?.version !== 'number') throw usageError('考次详情中没有 attempt.version')
+          return data.attempt.version
+        },
+        log: (m) => ctx.log(m),
+        run: async ({ requestId, version }) => {
+          const base = { expectedRevision: version, score, publicComment, internalComment }
+          if (reason !== undefined) base.reason = reason
+          const { data } = await ctx.client.request({
+            method: 'PUT',
+            path: `/admin/ai-coding/attempts/${id}/grade`,
+            body: withRequestId(ctx, payloadFrom(ctx, base), requestId),
+          })
+          return data
+        },
+      })
+    }
+    // action === 'void'
+    if (!id) throw usageError('缺少考次 id', '用法：ch ai attempts void <id> --reason 原因')
+    const reason = requireReason(ctx, { label: 'ch ai attempts void <id> --reason 原因' })
+    return runWithVersionRetry({
+      explicitVersion: flagNumber(ctx, 'version'),
+      explicitRequestId: flagString(ctx, 'request-id'),
+      readVersion: async () => {
+        const { data } = await ctx.client.request({ method: 'GET', path: `/admin/ai-coding/attempts/${id}` })
+        if (typeof data?.attempt?.version !== 'number') throw usageError('考次详情中没有 attempt.version')
+        return data.attempt.version
+      },
+      log: (m) => ctx.log(m),
+      run: async ({ requestId, version }) => {
+        const { data } = await ctx.client.request({
+          method: 'POST',
+          path: `/admin/ai-coding/attempts/${id}/void`,
+          body: withRequestId(ctx, { version, reason }, requestId),
+        })
+        return data
+      },
+    })
+  },
+})
+
+/* ============================ ai candidates ============================ */
+
+const CANDIDATE_ACTIONS = new Set(['list', 'retake'])
+
+register('ai candidates', {
+  summary: 'AI Coding 考生资格：list/retake（安排重考）',
+  requestId: true,
+  usage: [
+    'ch ai candidates list [--page N] [--page-size N] [--plan-id N] [--group-id N] [--eligibility NOT_REQUIRED|WAITING_SELECTION|INELIGIBLE|EXEMPT|REQUIRED] [--keyword 关键词]',
+    'ch ai candidates retake <userId> --plan-id N --assignment-version N --opens-at "..." --closes-at "..." --reason 原因',
+  ].join('\n  '),
+  endpoints: ['GET /admin/ai-coding/candidates', 'POST /admin/ai-coding/candidates/{userId}/retake'],
+  run: async (ctx) => {
+    const [action, ...rest] = ctx.positionals
+    if (!CANDIDATE_ACTIONS.has(action)) {
+      throw usageError(`ai candidates 子命令必须是 ${[...CANDIDATE_ACTIONS].join('|')}`, '用法：ch help ai candidates')
+    }
+    if (action === 'list') {
+      const { data } = await ctx.client.request({
+        method: 'GET',
+        path: '/admin/ai-coding/candidates',
+        query: listQuery(ctx, {
+          'plan-id': { key: 'planId' },
+          'group-id': { key: 'groupId' },
+          eligibility: { key: 'eligibility' },
+          keyword: { key: 'keyword' },
+        }),
+      })
+      return data
+    }
+    const userId = idParam(rest[0], { label: 'userId' })
+    const planId = flagString(ctx, 'plan-id', { required: true, label: '--plan-id N' })
+    const assignmentVersion = flagNumber(ctx, 'assignment-version', { required: true, label: '--assignment-version N（取自 ch ai candidates list 的 assignmentVersion）' })
+    const opensAt = flagString(ctx, 'opens-at', { required: true, label: '--opens-at "2026-09-29 10:00"' })
+    const closesAt = flagString(ctx, 'closes-at', { required: true, label: '--closes-at "2026-09-29 12:00"' })
+    const reason = requireReason(ctx, { label: '--reason 重考原因' })
+    const { data } = await ctx.client.request({
+      method: 'POST',
+      path: `/admin/ai-coding/candidates/${userId}/retake`,
+      body: withRequestId(ctx, {
+        planId,
+        assignmentVersion,
+        opensAt: toShanghaiOffset(opensAt),
+        closesAt: toShanghaiOffset(closesAt),
+        reason,
+      }),
+    })
+    return data
+  },
+})

package/src/commands/analysis.mjs

@@ -0,0 +1,124 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { register } from './index.mjs'
+import { CliError, EXIT, usageError } from '../errors.mjs'
+import { flagString, flagNumber, flagOn, parseDataJson, parseBoolFlag } from '../payload.mjs'
+import { idParam } from '../path.mjs'
+const resources = JSON.parse(fs.readFileSync(new URL('../analysis-resources.json', import.meta.url), 'utf8'))
+
+const specs = new Map(resources.map(resource => [resource.name, resource]))
+const requirement = 'backend v36 data-analysis permission (CLI 0.3.0)'
+const read = { permission: 'data-analysis', backendRequirement: requirement }
+function resource(ctx) {
+  const name = ctx.positionals[0]
+  if (!specs.has(name)) throw usageError('未知分析资源', '运行 ch analysis resources 查看资源目录')
+  return name
+}
+function query(ctx, name) {
+  const size = flagNumber(ctx, 'size') ?? 100
+  if (!Number.isInteger(size) || size < 1 || size > 500) throw usageError('--size 须为 1–500 的整数')
+  const raw = flagString(ctx, 'filters')
+  const filters = raw === undefined ? {} : parseDataJson(raw, { label: '--filters' })
+  if (!filters || typeof filters !== 'object' || Array.isArray(filters) || Object.keys(filters).length > 16) throw usageError('--filters 必须是最多 16 个字段的对象')
+  for (const [key, value] of Object.entries(filters)) {
+    const declared = specs.get(name).filters
+    const type = Object.hasOwn(declared, key) ? declared[key] : undefined
+    if (!type || (type === 'integer' && (!Number.isSafeInteger(value) || value < 0)) ||
+      (type === 'boolean' && typeof value !== 'boolean') ||
+      (type === 'string' && (typeof value !== 'string' || value.length > 200))) throw usageError(`不适用的过滤字段或取值：${key}`)
+  }
+  const cursor = flagString(ctx, 'cursor')
+  if (cursor && (!/^[A-Za-z0-9_-]+$/.test(cursor) || cursor.length > 2048)) throw usageError('--cursor 无效')
+  return [['size', size], ['filters', JSON.stringify(filters)], ['cursor', cursor]]
+}
+function destination(ctx) {
+  const out = path.resolve(flagString(ctx, 'out', { required: true }))
+  try { if (!fs.statSync(path.dirname(out)).isDirectory()) throw Error() } catch { throw usageError('--out 父目录不存在') }
+  if (fs.existsSync(out) && (!flagOn(ctx, 'force') || !fs.lstatSync(out).isFile())) throw usageError('目标已存在或不是普通文件；覆盖普通文件需 --force')
+  return out
+}
+function publish(temp, out, force) {
+  // link is atomic and refuses a race-created target. --force uses atomic replacement.
+  if (force) fs.renameSync(temp, out)
+  else { fs.linkSync(temp, out); fs.unlinkSync(temp) }
+}
+function responseError(message) { return new CliError({ code: 'UNEXPECTED_RESPONSE', message, exitCode: EXIT.BUSINESS }) }
+
+register('analysis resources', {
+  ...read, summary: '查询全量只读数据目录、字段、过滤条件及实际后端可用性', usage: 'ch analysis resources',
+  endpoints: ['GET /admin/analysis/resources'],
+  run: async ctx => (await ctx.client.request({ path: '/admin/analysis/resources' })).data,
+})
+register('analysis list', {
+  ...read, summary: '按主键游标查询全量业务数据（不推进业务状态）',
+  usage: 'ch analysis list <resource> [--cursor 游标] [--size 100] [--filters JSON或@文件]',
+  endpoints: ['GET /admin/analysis/resources/{resource}'],
+  run: async ctx => { const name = resource(ctx); return (await ctx.client.request({ path: `/admin/analysis/resources/${name}`, query: query(ctx, name) })).data },
+})
+register('analysis get', {
+  ...read, summary: '读取单条分析记录，包括题目、答卷和评价（按字段白名单）',
+  usage: 'ch analysis get <resource> <id>', endpoints: ['GET /admin/analysis/resources/{resource}/{id}'],
+  run: async ctx => { const name = resource(ctx); const id = idParam(ctx.positionals[1]); if (BigInt(id) < 1n) throw usageError('id 须为正整数'); return (await ctx.client.request({ path: `/admin/analysis/resources/${name}/${id}` })).data },
+})
+register('analysis export', {
+  ...read, localWrite: true, summary: '逐页导出 JSONL，全部成功后原子落盘；多页不是同一时刻快照',
+  usage: 'ch analysis export <resource> --out ./data.jsonl [--size 100] [--filters JSON或@文件] [--force]',
+  endpoints: ['GET /admin/analysis/resources/{resource}'],
+  run: async ctx => {
+    const name = resource(ctx), args = query(ctx, name), out = destination(ctx)
+    const temp = `${out}.partial-${crypto.randomUUID()}`
+    const fd = fs.openSync(temp, 'wx', 0o600)
+    let count = 0, pages = 0, upperBound = null, cursor, last = 0n
+    const seen = new Set()
+    try {
+      do {
+        const { data } = await ctx.client.request({ path: `/admin/analysis/resources/${name}`, query: args.filter(([key]) => key !== 'cursor').concat([['cursor', cursor]]) })
+        if (!data || data.resource !== name || !Array.isArray(data.items) || !/^\d+$/.test(String(data.upperBound)) ||
+          (data.nextCursor !== null && (typeof data.nextCursor !== 'string' || !/^[A-Za-z0-9_-]+$/.test(data.nextCursor)))) throw responseError('分析分页响应无效')
+        if (upperBound !== null && upperBound !== data.upperBound) throw responseError('导出期间分页上界改变')
+        upperBound = data.upperBound
+        for (const row of data.items) {
+          const id = String(row?.[specs.get(name).key])
+          if (!/^\d+$/.test(id) || BigInt(id) <= last || BigInt(id) > BigInt(upperBound)) throw responseError('分析分页记录顺序或主键无效')
+          last = BigInt(id); fs.writeSync(fd, JSON.stringify(row) + '\n'); count++
+        }
+        pages++; cursor = data.nextCursor
+        if (cursor && (seen.has(cursor) || data.items.length === 0)) throw responseError('分析分页游标重复或没有进展')
+        if (cursor) seen.add(cursor)
+      } while (cursor)
+      fs.fsyncSync(fd); fs.closeSync(fd); publish(temp, out, flagOn(ctx, 'force'))
+    } catch (error) {
+      try { fs.closeSync(fd) } catch {}
+      try { fs.unlinkSync(temp) } catch {}
+      throw error
+    }
+    return { savedTo: out, resource: name, records: count, pages, upperBound, consistency: 'bounded-live-read; not a transaction snapshot across pages' }
+  },
+})
+register('analysis download', {
+  ...read, localWrite: true, summary: '受鉴权下载分析附件到本地；不支持任意 URL 或服务器路径',
+  usage: 'ch analysis download <attachmentId> --out ./attachment [--force]',
+  endpoints: ['GET /admin/analysis/attachments/{attachmentId}'],
+  run: async ctx => {
+    const id = ctx.positionals[0]
+    if (!/^(?:ai-[a-f0-9]{32}\.[a-z0-9]{2,5}|plan-[1-9]\d*-(?:assessment-file|assessment-image|pass-image|fail-image))$/.test(id ?? '')) throw usageError('attachmentId 无效，请使用分析记录中的 analysisAttachments.id')
+    const out = destination(ctx)
+    const { buffer, contentType } = await ctx.client.request({ path: `/admin/analysis/attachments/${id}`, raw: true })
+    const temp = `${out}.partial-${crypto.randomUUID()}`
+    try { fs.writeFileSync(temp, buffer, { flag: 'wx', mode: 0o600 }); publish(temp, out, flagOn(ctx, 'force')) }
+    catch (error) { try { fs.unlinkSync(temp) } catch {}; throw error }
+    return { savedTo: out, bytes: buffer.length, contentType }
+  },
+})
+register('accounts analysis-permission', {
+  permission: 'SYSTEM', backendRequirement: requirement, summary: 'SYSTEM 开启/关闭管理员数据分析权限（版本冲突须刷新）',
+  usage: 'ch accounts analysis-permission <id> --enabled true|false --version N',
+  endpoints: ['PUT /admin/accounts/{id}/data-analysis-permission'],
+  run: async ctx => {
+    const id = idParam(ctx.positionals[0]), enabled = parseBoolFlag(flagString(ctx, 'enabled', { required: true }), { flag: 'enabled' })
+    const version = flagNumber(ctx, 'version', { required: true })
+    if (!Number.isSafeInteger(version) || version < 0) throw usageError('--version 须为非负整数')
+    return (await ctx.client.request({ method: 'PUT', path: `/admin/accounts/${id}/data-analysis-permission`, body: { enabled, version } })).data
+  },
+})

package/src/commands/api.mjs

@@ -0,0 +1,63 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { toArray } from '../argv.mjs'
+import { parseDataJson, flagOn } from '../payload.mjs'
+
+const METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+
+/**
+ * 通用兜底：调用任意 API 端点。
+ * 语义化命令未覆盖的长尾端点、新上线端点均可用它触达，保证 CLI 与后端能力同步。
+ */
+register('api', {
+  summary: '通用兜底：调用任意 API 端点',
+  usage: 'ch api <METHOD> <path> [-q key=value ...] [-d <json|@file>] [-H "Name: value" ...] [--public]',
+  endpoints: [],
+  // 逃生舱：未被 CLI 语义化的新端点参数也必须能发出去，所以跳过未知 flag 与 arity 检查
+  permissiveFlags: true,
+  run: async (ctx) => {
+    const [methodRaw, requestPath] = ctx.positionals
+    if (!methodRaw || !requestPath) {
+      throw usageError('缺少 METHOD 或 path', '用法：ch api GET /admin/dashboard')
+    }
+    const method = String(methodRaw).toUpperCase()
+    if (!METHODS.has(method)) {
+      throw usageError(`不支持的 HTTP 方法：${methodRaw}`, `可用：${[...METHODS].join(' / ')}`)
+    }
+
+    const query = []
+    for (const entry of toArray(ctx.multi.get('q'))) {
+      const text = String(entry)
+      const idx = text.indexOf('=')
+      const key = idx >= 0 ? text.slice(0, idx) : text
+      const value = idx >= 0 ? text.slice(idx + 1) : ''
+      if (key) query.push([key, value])
+    }
+
+    const headers = {}
+    for (const entry of toArray(ctx.multi.get('H'))) {
+      const text = String(entry)
+      const idx = text.indexOf(':')
+      if (idx <= 0) throw usageError(`请求头格式应为 "Name: value"：${text}`)
+      headers[text.slice(0, idx).trim()] = text.slice(idx + 1).trim()
+    }
+
+    let body
+    const rawBody = ctx.flags.get('d')
+    if (rawBody !== undefined && rawBody !== '') {
+      body = parseDataJson(rawBody, { label: '-d' })
+    }
+
+    const { data } = await ctx.client.request({
+      method,
+      path: requestPath,
+      query,
+      body,
+      headers,
+      noAuth: flagOn(ctx, 'public'),
+      // 逃生舱：允许把查询串直接写在 path 里（语义化命令不允许，见 client.mjs buildUrl）
+      allowQuery: true,
+    })
+    return data
+  },
+})