@quantacenter/quanta-problem-cli 0.0.0-stage → 1.0.1

package/dist/program.d.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+
+/** 与 packages/challenge-web-app/server/trpc/schemas/publish-schema.ts 保持一致 */
+declare const DIFFICULTIES: readonly ["easy", "medium", "hard", "very_hard"];
+type Difficulty = (typeof DIFFICULTIES)[number];
+/** 默认站点根目录：live-server 镜像与 initCommand 都以 `project` 为根 */
+declare const DEFAULT_JUDGE_UPLOAD_PATH = "project";
+declare const DEFAULT_INIT_COMMAND = "npx serve -l 3000 project";
+declare const problemConfigSchema: z.ZodObject<{
+    title: z.ZodString;
+    problemId: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodDefault<z.ZodEnum<{
+        frontend: "frontend";
+        backend_service: "backend_service";
+    }>>;
+    detail: z.ZodOptional<z.ZodString>;
+    detailFile: z.ZodOptional<z.ZodString>;
+    difficulty: z.ZodEnum<{
+        easy: "easy";
+        medium: "medium";
+        hard: "hard";
+        very_hard: "very_hard";
+    }>;
+    tagIds: z.ZodArray<z.ZodNumber>;
+    totalScore: z.ZodOptional<z.ZodNumber>;
+    cover: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        mode: z.ZodLiteral<"default">;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"custom">;
+        imageId: z.ZodOptional<z.ZodString>;
+        generate: z.ZodOptional<z.ZodObject<{
+            bg: z.ZodDefault<z.ZodString>;
+            bgTo: z.ZodOptional<z.ZodString>;
+            accent: z.ZodDefault<z.ZodString>;
+            text: z.ZodDefault<z.ZodString>;
+            subtitle: z.ZodOptional<z.ZodString>;
+            footer: z.ZodOptional<z.ZodString>;
+            width: z.ZodDefault<z.ZodNumber>;
+            height: z.ZodDefault<z.ZodNumber>;
+            out: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
+    runtime: z.ZodDefault<z.ZodObject<{
+        judgeUploadPath: z.ZodDefault<z.ZodString>;
+        initCommand: z.ZodDefault<z.ZodString>;
+        buildCommand: z.ZodOptional<z.ZodString>;
+        bootCommand: z.ZodOptional<z.ZodString>;
+        serviceImage: z.ZodOptional<z.ZodEnum<{
+            "node-24": "node-24";
+        }>>;
+        servicePort: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    paths: z.ZodDefault<z.ZodObject<{
+        template: z.ZodDefault<z.ZodString>;
+        answer: z.ZodDefault<z.ZodString>;
+        judge: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ProblemConfigInput = z.input<typeof problemConfigSchema>;
+type ProblemConfig = z.output<typeof problemConfigSchema>;
+
+/** 判题脚本的静态分析：把常见坑（检查点不 return、点击 disabled 按钮、断言消息缺信息）在本地毫秒级挡住。策略是先把注释/字符串"打码"成等长 mask，再做括号配对与调用点查找，避免被字符串里的括号带偏。 */
+interface Checkpoint {
+    name: string;
+    score: number;
+    /** 1-based 行号 */
+    line: number;
+    /** 是否 return 了具体分数（return; / 无 return 都是 false） */
+    returnsValue: boolean;
+}
+interface Located<T> {
+    line: number;
+    value: T;
+}
+interface JudgeScriptAnalysis {
+    /** 是否写了 `export default ...`（判题机靠文本替换 `export default ` → `const run = `） */
+    hasDefaultExport: boolean;
+    hasDefineTestHandler: boolean;
+    /** 除 default 之外的导出，会残留在沙箱模块里，属于可疑写法 */
+    namedExports: string[];
+    checkpoints: Checkpoint[];
+    /** 各检查点分值之和（解析不到的一律计 0 并单独报告） */
+    checkpointTotal: number;
+    unparsedCheckpoints: Located<string>[];
+    clickWithoutTimeout: Located<string>[];
+    /** 断言消息缺少"期望 vs 实际"（学生看不懂失败原因） */
+    vagueExpectations: Located<string>[];
+    expectationCount: number;
+    lineCount: number;
+}
+
+type Severity = 'error' | 'warn' | 'info';
+interface Finding {
+    /** 规则编号，可与 docs/RULES.md 对照；CI 里可以按编号豁免 */
+    rule: string;
+    severity: Severity;
+    message: string;
+    /** 相对题目目录的路径 */
+    file?: string;
+    line?: number;
+    hint?: string;
+}
+interface ValidationReport {
+    findings: Finding[];
+    errors: number;
+    warnings: number;
+    /** 无 error 即视为通过（warning 默认不阻塞，--strict 时才阻塞） */
+    ok: boolean;
+    totalScore: number;
+    stats: {
+        checkpointCount: number;
+        judgeLines: number;
+        template: ArtifactStats;
+        answer: ArtifactStats;
+    };
+    analysis: JudgeScriptAnalysis;
+    templateSnapshot: Record<string, string>;
+    answerSnapshot: Record<string, string>;
+}
+interface ArtifactStats {
+    fileCount: number;
+    totalBytes: number;
+    ignored: string[];
+}
+
+declare const CLI_NAME = "qpc";
+declare const CLI_VERSION: string;
+
+/** 包的程序化入口（exports/main 指向这里）：零副作用，与 bin 入口分开以避免 jiti 加载配置时把 CLI 跑一遍；只依赖 problem-config-schema（纯 zod）。 */
+
+/** 出题配置的类型助手（运行时恒等函数）；返回值刻意声明为 ProblemConfigInput 而非泛型 T，让拼错的字段名触发多余属性检查。 */
+declare const defineProblemConfig: (config: ProblemConfigInput) => ProblemConfigInput;
+
+export { CLI_NAME, CLI_VERSION, DEFAULT_INIT_COMMAND, DEFAULT_JUDGE_UPLOAD_PATH, DIFFICULTIES, type Difficulty, type Finding, type ProblemConfig, type ProblemConfigInput, type Severity, type ValidationReport, defineProblemConfig, problemConfigSchema };

package/dist/program.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { readFileSync } from 'fs';
+
+// ../shared/service/backend-service-image.ts
+var PNPM_VERSION = "9.15.9";
+var BACKEND_SERVICE_IMAGES = {
+  "node-24": {
+    id: "node-24",
+    label: "Node.js 24",
+    image: "challenge-backend-service-agent",
+    editorBootCommand: (mountPath) => [
+      `[install-pnpm] npm install --global pnpm@${PNPM_VERSION}`,
+      `[install] pnpm --dir ./${mountPath} install`
+    ].join("\n"),
+    // 入口由题目的 package.json 决定；npm 在没有 scripts.start 时回退到 node server.js。
+    initCommand: (mountPath) => `[dev-server] cd ./${mountPath} && npm start`,
+    defaultPort: 3e3
+  }
+};
+var BACKEND_SERVICE_IMAGE_IDS = Object.keys(
+  BACKEND_SERVICE_IMAGES
+);
+Object.values(
+  BACKEND_SERVICE_IMAGES
+).map((item) => item.image);
+
+// src/domain/cover.ts
+var COVER_DEFAULTS = {
+  bg: "#0F172A",
+  accent: "#A6FB1D",
+  text: "#F8FAFC",
+  width: 1200,
+  height: 675
+};
+
+// src/domain/problem-config-schema.ts
+var DIFFICULTIES = ["easy", "medium", "hard", "very_hard"];
+var DEFAULT_JUDGE_UPLOAD_PATH = "project";
+var DEFAULT_INIT_COMMAND = "npx serve -l 3000 project";
+var PROBLEM_TYPES = ["frontend", "backend_service"];
+var coverGenerateSchema = z.object({
+  /** 背景色（纯色；配合 bgTo 变成对角线渐变） */
+  bg: z.string().default(COVER_DEFAULTS.bg),
+  /** 渐变终止色，留空 = 纯色背景 */
+  bgTo: z.string().optional(),
+  /** 强调色：左侧竖条 + 副标题 */
+  accent: z.string().default(COVER_DEFAULTS.accent),
+  /** 主标题颜色 */
+  text: z.string().default(COVER_DEFAULTS.text),
+  /** 副标题（建议写接口清单或一句话简介），留空则不渲染 */
+  subtitle: z.string().optional(),
+  /** 左下角页脚，默认 “Quanta Challenge” */
+  footer: z.string().optional(),
+  width: z.number().int().min(200).max(4096).default(COVER_DEFAULTS.width),
+  height: z.number().int().min(200).max(4096).default(COVER_DEFAULTS.height),
+  /** 输出文件（相对题目目录） */
+  out: z.string().default("cover.png")
+});
+var coverSchema = z.union([
+  z.object({ mode: z.literal("default") }),
+  z.object({
+    mode: z.literal("custom"),
+    /** 平台上的图片 id；`qpc cover --upload --write` 会把生成结果写回这里 */
+    imageId: z.string().min(1).optional(),
+    /** 配置了就能用 `qpc cover` 一键生成（后端题型必须自定义封面） */
+    generate: coverGenerateSchema.optional()
+  })
+]);
+var problemConfigSchema = z.object({
+  title: z.string().min(1, "title \u4E0D\u80FD\u4E3A\u7A7A"),
+  /** 平台题目 id（qpc upload 返回的 pid）：填了它就在该题目下追加新版本，否则每次新建 */
+  problemId: z.number().int().positive().optional(),
+  /** 题型；缺省为前端，老题目不需要改配置 */
+  type: z.enum(PROBLEM_TYPES).default("frontend"),
+  /** 题面正文；与 detailFile 二选一 */
+  detail: z.string().min(1).optional(),
+  /** 题面文件（相对题目目录），便于把长题面单独放一个 markdown */
+  detailFile: z.string().min(1).optional(),
+  difficulty: z.enum(DIFFICULTIES),
+  tagIds: z.array(z.number().int().positive()).min(1, "tagIds \u81F3\u5C11\u9700\u8981\u4E00\u4E2A\u6807\u7B7E\uFF08\u7528 `qpc tag` \u67E5\u770B\u53EF\u7528 id\uFF09"),
+  /** 留空表示"以判题脚本里各检查点之和为准"；填写则必须与之和相等 */
+  totalScore: z.number().int().positive().optional(),
+  cover: coverSchema.default({ mode: "default" }),
+  runtime: z.object({
+    /** 判题时打包上传的目录，同时决定快照挂载路径（快照键为 `/<judgeUploadPath>/...`） */
+    judgeUploadPath: z.string().min(1).default(DEFAULT_JUDGE_UPLOAD_PATH),
+    initCommand: z.string().min(1).default(DEFAULT_INIT_COMMAND),
+    buildCommand: z.string().min(1).optional(),
+    bootCommand: z.string().min(1).optional(),
+    /** 后端服务：初始镜像 id（不是 docker 镜像名，取值见 @challenge/shared/backend-service-image） */
+    serviceImage: z.enum(BACKEND_SERVICE_IMAGE_IDS).optional(),
+    /** 后端服务：服务监听端口（也是判题机请求的端口） */
+    servicePort: z.number().int().positive().max(65535).default(3e3)
+  }).default({
+    judgeUploadPath: DEFAULT_JUDGE_UPLOAD_PATH,
+    initCommand: DEFAULT_INIT_COMMAND,
+    servicePort: 3e3
+  }),
+  paths: z.object({
+    template: z.string().min(1).default("template"),
+    answer: z.string().min(1).default("answer"),
+    judge: z.string().min(1).default("judge.js")
+  }).default({ template: "template", answer: "answer", judge: "judge.js" })
+});
+var CLI_NAME = "qpc";
+var readVersion = () => {
+  try {
+    const raw = readFileSync(
+      new URL("../package.json", import.meta.url),
+      "utf8"
+    );
+    const parsed = JSON.parse(raw);
+    return parsed.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+};
+var CLI_VERSION = readVersion();
+
+// src/program.ts
+var defineProblemConfig = (config) => config;
+
+export { CLI_NAME, CLI_VERSION, DEFAULT_INIT_COMMAND, DEFAULT_JUDGE_UPLOAD_PATH, DIFFICULTIES, defineProblemConfig, problemConfigSchema };
+//# sourceMappingURL=program.js.map
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../shared/service/backend-service-image.ts","../src/domain/cover.ts","../src/domain/problem-config-schema.ts","../src/version.ts","../src/program.ts"],"names":[],"mappings":"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","file":"program.js","sourcesContent":["export interface BackendServiceImage {\n   /** 存进数据库的稳定 id，也是下拉选项的 value（不要改，改了要写数据迁移） */\n   id: string;\n   /** 展示名，带版本号 */\n   label: string;\n   /** 真正拉起容器的 docker 镜像名 */\n   image: string;\n   /** 编辑器（WebContainer）里的一次性准备步骤，`mountPath` = 题目的 judgeUploadPath */\n   editorBootCommand: (mountPath: string) => string;\n   /** 服务启动命令，编辑器与判题容器共用 */\n   initCommand: (mountPath: string) => string;\n   defaultPort: number;\n}\n\nconst PNPM_VERSION = '9.15.9';\n\nexport const BACKEND_SERVICE_IMAGES = {\n   'node-24': {\n      id: 'node-24',\n      label: 'Node.js 24',\n      image: 'challenge-backend-service-agent',\n      editorBootCommand: (mountPath: string) =>\n         [\n            `[install-pnpm] npm install --global pnpm@${PNPM_VERSION}`,\n            `[install] pnpm --dir ./${mountPath} install`,\n         ].join('\\n'),\n      // 入口由题目的 package.json 决定；npm 在没有 scripts.start 时回退到 node server.js。\n      initCommand: (mountPath: string) =>\n         `[dev-server] cd ./${mountPath} && npm start`,\n      defaultPort: 3000,\n   },\n} as const satisfies Record<string, BackendServiceImage>;\n\nexport type BackendServiceImageId = keyof typeof BACKEND_SERVICE_IMAGES;\n\nexport const BACKEND_SERVICE_IMAGE_IDS = Object.keys(\n   BACKEND_SERVICE_IMAGES\n) as BackendServiceImageId[];\n\nexport const DEFAULT_BACKEND_SERVICE_IMAGE_ID: BackendServiceImageId =\n   'node-24';\n\nconst isBackendServiceImageId = (\n   value: unknown\n): value is BackendServiceImageId =>\n   typeof value === 'string' &&\n   Object.prototype.hasOwnProperty.call(BACKEND_SERVICE_IMAGES, value);\n\n/** 只认注册表 id：空值 / 未知值一律收敛成默认镜像。 */\nexport const normalizeBackendServiceImageId = (\n   id?: string | null\n): BackendServiceImageId =>\n   isBackendServiceImageId(id) ? id : DEFAULT_BACKEND_SERVICE_IMAGE_ID;\n\nconst getBackendServiceImage = (\n   id?: string | null\n): BackendServiceImage =>\n   BACKEND_SERVICE_IMAGES[normalizeBackendServiceImageId(id)];\n\n/** 库里的 id → 真正拉起的 docker 镜像名。 */\nexport const resolveBackendServiceImageName = (id?: string | null): string =>\n   getBackendServiceImage(id).image;\n\nexport const buildBackendBootCommand = (\n   id: string | null | undefined,\n   mountPath: string\n): string => getBackendServiceImage(id).editorBootCommand(mountPath);\n\nexport const buildBackendInitCommand = (\n   id: string | null | undefined,\n   mountPath: string\n): string => getBackendServiceImage(id).initCommand(mountPath);\n\nexport const getBackendServiceDefaultPort = (id?: string | null): number =>\n   getBackendServiceImage(id).defaultPort;\n\n/** 所有后端题容器镜像（调度器清扫器用来回收泄漏容器）。 */\nexport const BACKEND_SERVICE_CONTAINER_IMAGES = Object.values(\n   BACKEND_SERVICE_IMAGES\n).map((item) => item.image);\n","import { UsageError } from '../core/errors';\n\nexport interface CoverSpec {\n   /** 主标题（必填）。过长会自动换行并缩小字号 */\n   title: string;\n   /** 强调色副标题，例如接口清单或一句话简介 */\n   subtitle?: string;\n   /** 左下角页脚，默认 \"Quanta Challenge\" */\n   footer?: string;\n   /** 背景色（`#rgb` / `#rrggbb`） */\n   bg: string;\n   /** 渐变终止色；给了就画对角线渐变，否则纯色 */\n   bgTo?: string;\n   /** 强调色：竖条 + 副标题 */\n   accent: string;\n   /** 主标题颜色 */\n   text: string;\n   /** 画布宽高（像素） */\n   width: number;\n   height: number;\n}\n\nexport const COVER_DEFAULTS = {\n   bg: '#0F172A',\n   accent: '#A6FB1D',\n   text: '#F8FAFC',\n   footer: 'Quanta Challenge',\n   width: 1200,\n   height: 675,\n} as const;\n\n/** 手写那版封面的渐变终止色，作为 `--bg-to` 的推荐值写进文档 */\nexport const COVER_SUGGESTED_BG_TO = '#14432A';\n\nconst HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;\n\nexport const isHexColor = (value: string): boolean => HEX_COLOR.test(value);\n\nexport const assertHexColor = (value: string, field: string): string => {\n   if (!isHexColor(value)) {\n      throw new UsageError(\n         `${field} 必须是十六进制颜色（#rgb / #rrggbb），当前为 \"${value}\"`,\n         { hint: '例如 --bg \"#0F172A\" --accent \"#A6FB1D\"。' },\n      );\n   }\n   return value;\n};\n\nconst XML_ESCAPES: Record<string, string> = {\n   '&': '&amp;',\n   '<': '&lt;',\n   '>': '&gt;',\n   '\"': '&quot;',\n   \"'\": '&apos;',\n};\n\nexport const escapeXml = (value: string): string =>\n   value.replace(/[&<>\"']/g, (char) => XML_ESCAPES[char] ?? char);\n\n/** 全角/宽字符判定（与 logger 的显示宽度判定同源，用于估算排版宽度） */\nconst isWideChar = (code: number): boolean =>\n   (code >= 0x1100 && code <= 0x115f) ||\n   (code >= 0x2e80 && code <= 0xa4cf) ||\n   (code >= 0xac00 && code <= 0xd7a3) ||\n   (code >= 0xf900 && code <= 0xfaff) ||\n   (code >= 0xfe30 && code <= 0xfe6f) ||\n   (code >= 0xff00 && code <= 0xff60) ||\n   (code >= 0xffe0 && code <= 0xffe6);\n\n/** 单字符宽度，单位是 em（相对当前字号） */\nconst charWidthEm = (char: string, bold: boolean): number => {\n   const code = char.codePointAt(0) ?? 0;\n   if (isWideChar(code)) return 1;\n   if (char === ' ') return 0.28;\n   if (\"ilj.,:;'|!\".includes(char)) return 0.3;\n   if (/[A-Z]/.test(char)) return bold ? 0.68 : 0.66;\n   if (/[0-9]/.test(char)) return 0.58;\n   return bold ? 0.6 : 0.56;\n};\n\nconst textWidthEm = (text: string, bold: boolean): number =>\n   [...text].reduce((sum, char) => sum + charWidthEm(char, bold), 0);\n\n/** 可以在其后断行的位置：空格之后，或任意宽字符之后（中文没有空格） */\nconst isBreakAfter = (char: string): boolean =>\n   char === ' ' || isWideChar(char.codePointAt(0) ?? 0);\n\nexport const wrapByWidth = (\n   text: string,\n   maxWidthEm: number,\n   bold = true,\n): string[] => {\n   const lines: string[] = [];\n   let current = '';\n   let currentEm = 0;\n   let breakAt = -1;\n   let breakEm = 0;\n\n   const flush = (at: number, em: number) => {\n      const line = (at >= 0 ? current.slice(0, at) : current).trim();\n      if (line) lines.push(line);\n      current = at >= 0 ? current.slice(at).trimStart() : '';\n      currentEm = at >= 0 ? currentEm - em : 0;\n      breakAt = -1;\n      breakEm = 0;\n   };\n\n   for (const char of text) {\n      const width = charWidthEm(char, bold);\n      if (currentEm + width > maxWidthEm && current) {\n         // 只有断点足够靠后（>40% 行宽）才用它，否则宁可硬切，避免出现极短的尾行\n         if (breakAt > 0 && breakEm > maxWidthEm * 0.4) {\n            flush(breakAt, breakEm);\n         } else {\n            flush(-1, currentEm);\n         }\n      }\n      current += char;\n      currentEm += width;\n      if (isBreakAfter(char)) {\n         breakAt = current.length;\n         breakEm = currentEm;\n      }\n   }\n   if (current.trim()) lines.push(current.trim());\n   return lines.length > 0 ? lines : [''];\n};\n\nexport interface CoverLayout {\n   lines: string[];\n   fontSize: number;\n   lineHeight: number;\n   barX: number;\n   barY: number;\n   barWidth: number;\n   barHeight: number;\n   textX: number;\n   firstBaseline: number;\n   subtitleBaseline: number;\n   subtitleFontSize: number;\n   footerBaseline: number;\n   footerFontSize: number;\n}\n\n/** 字号从基准值往下收敛直到能塞进 maxLines 行，下限 0.5 × 基准（再小不可读，宁可标题多占一行）。 */\nexport const layoutCover = (spec: CoverSpec): CoverLayout => {\n   const scale = spec.width / COVER_DEFAULTS.width;\n   const pad = 72 * scale;\n   const barWidth = 6 * scale;\n   const textX = pad + barWidth + 26 * scale;\n   const contentWidth = spec.width - textX - pad;\n   const baseFontSize = 58 * scale;\n   const minFontSize = Math.max(20, baseFontSize * 0.5);\n   const maxLines = 3;\n\n   let fontSize = baseFontSize;\n   let lines = wrapByWidth(spec.title, contentWidth / fontSize, true);\n   for (let size = baseFontSize; size >= minFontSize; size -= 2) {\n      const candidate = wrapByWidth(spec.title, contentWidth / size, true);\n      const fits = candidate.every(\n         (line) => textWidthEm(line, true) * size <= contentWidth + 0.5,\n      );\n      if (fits && candidate.length <= maxLines) {\n         fontSize = size;\n         lines = candidate;\n         break;\n      }\n      fontSize = size;\n      lines = candidate;\n   }\n\n   const lineHeight = fontSize * 1.22;\n   const blockTop = pad + 24 * scale;\n   const textBaseline = blockTop + fontSize;\n   const barHeight = lineHeight * (lines.length - 1) + fontSize * 1.02;\n   const subtitleFontSize = 26 * scale;\n   const subtitleBaseline =\n      blockTop + lineHeight * (lines.length - 1) + fontSize * 0.62 + 72 * scale;\n\n   return {\n      lines,\n      fontSize,\n      lineHeight,\n      barX: pad,\n      barY: blockTop + fontSize * 0.06,\n      barWidth,\n      barHeight,\n      textX,\n      firstBaseline: textBaseline,\n      subtitleBaseline,\n      subtitleFontSize,\n      footerBaseline: spec.height - 60 * scale,\n      footerFontSize: 24 * scale,\n   };\n};\n\nconst fontStack = (mono: boolean): string =>\n   mono\n      ? \"'Menlo','Monaco','Courier New',monospace\"\n      : \"'PingFang SC','Hiragino Sans GB','Microsoft YaHei','Noto Sans CJK SC','Source Han Sans SC',sans-serif\";\n\nexport const buildCoverSvg = (spec: CoverSpec): string => {\n   assertHexColor(spec.bg, '背景色');\n   assertHexColor(spec.accent, '强调色');\n   assertHexColor(spec.text, '标题颜色');\n   if (spec.bgTo !== undefined) assertHexColor(spec.bgTo, '渐变终止色');\n\n   const layout = layoutCover(spec);\n   const background =\n      spec.bgTo === undefined\n         ? `<rect width=\"${spec.width}\" height=\"${spec.height}\" fill=\"${spec.bg}\"/>`\n         : `<defs><linearGradient id=\"bg\" x1=\"0\" y1=\"0\" x2=\"1\" y2=\"1\">` +\n           `<stop offset=\"0%\" stop-color=\"${spec.bg}\"/>` +\n           `<stop offset=\"100%\" stop-color=\"${spec.bgTo}\"/></linearGradient></defs>` +\n           `<rect width=\"${spec.width}\" height=\"${spec.height}\" fill=\"url(#bg)\"/>`;\n\n   const titleLines = layout.lines\n      .map(\n         (line, index) =>\n            `<text x=\"${layout.textX}\" y=\"${round(layout.firstBaseline + index * layout.lineHeight)}\" ` +\n            `font-family=\"${fontStack(false)}\" font-size=\"${round(layout.fontSize)}\" ` +\n            `font-weight=\"700\" fill=\"${spec.text}\">${escapeXml(line)}</text>`,\n      )\n      .join('\\n');\n\n   const subtitle = spec.subtitle\n      ? `<text x=\"${layout.textX}\" y=\"${round(layout.subtitleBaseline)}\" ` +\n        `font-family=\"${fontStack(true)}\" font-size=\"${round(layout.subtitleFontSize)}\" ` +\n        `font-weight=\"700\" fill=\"${spec.accent}\">${escapeXml(spec.subtitle)}</text>`\n      : '';\n\n   const footer =\n      `<text x=\"${layout.barX}\" y=\"${round(layout.footerBaseline)}\" ` +\n      `font-family=\"${fontStack(false)}\" font-size=\"${round(layout.footerFontSize)}\" ` +\n      `fill=\"#64748B\">${escapeXml(spec.footer ?? COVER_DEFAULTS.footer)}</text>`;\n\n   return [\n      `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${spec.width}\" height=\"${spec.height}\" viewBox=\"0 0 ${spec.width} ${spec.height}\">`,\n      background,\n      `<rect x=\"${layout.barX}\" y=\"${round(layout.barY)}\" width=\"${layout.barWidth}\" height=\"${round(layout.barHeight)}\" rx=\"${layout.barWidth / 2}\" fill=\"${spec.accent}\"/>`,\n      titleLines,\n      subtitle,\n      footer,\n      '</svg>',\n   ]\n      .filter(Boolean)\n      .join('\\n');\n};\n\nconst round = (value: number): number => Math.round(value * 100) / 100;\n","import {\n   BACKEND_SERVICE_IMAGE_IDS,\n   buildBackendBootCommand,\n   buildBackendInitCommand,\n   getBackendServiceDefaultPort,\n   normalizeBackendServiceImageId,\n} from '@challenge/shared/backend-service-image';\nimport { z } from 'zod';\n\nimport { COVER_DEFAULTS } from './cover';\n\n/** 与 packages/challenge-web-app/server/trpc/schemas/publish-schema.ts 保持一致 */\nexport const DIFFICULTIES = ['easy', 'medium', 'hard', 'very_hard'] as const;\nexport type Difficulty = (typeof DIFFICULTIES)[number];\n\nexport const DEFAULT_CONFIG_FILES = [\n   'problem.config.ts',\n   'problem.config.mts',\n   'problem.config.js',\n   'problem.config.mjs',\n   'problem.config.json',\n] as const;\n\n/** 默认站点根目录：live-server 镜像与 initCommand 都以 `project` 为根 */\nexport const DEFAULT_JUDGE_UPLOAD_PATH = 'project';\nexport const DEFAULT_INIT_COMMAND = 'npx serve -l 3000 project';\n\n/** 题型：前端（静态站点 + Playwright）或后端服务（常驻进程 + HTTP 判题） */\nexport const PROBLEM_TYPES = ['frontend', 'backend_service'] as const;\nexport type ProblemType = (typeof PROBLEM_TYPES)[number];\n\n/** 本地生成封面的配色与排版：不随上传发给服务端（服务端只认 imageId），`qpc cover` 渲染 PNG 后由 --write 写回 imageId。 */\nexport const coverGenerateSchema = z.object({\n   /** 背景色（纯色；配合 bgTo 变成对角线渐变） */\n   bg: z.string().default(COVER_DEFAULTS.bg),\n   /** 渐变终止色，留空 = 纯色背景 */\n   bgTo: z.string().optional(),\n   /** 强调色：左侧竖条 + 副标题 */\n   accent: z.string().default(COVER_DEFAULTS.accent),\n   /** 主标题颜色 */\n   text: z.string().default(COVER_DEFAULTS.text),\n   /** 副标题（建议写接口清单或一句话简介），留空则不渲染 */\n   subtitle: z.string().optional(),\n   /** 左下角页脚，默认 “Quanta Challenge” */\n   footer: z.string().optional(),\n   width: z.number().int().min(200).max(4096).default(COVER_DEFAULTS.width),\n   height: z.number().int().min(200).max(4096).default(COVER_DEFAULTS.height),\n   /** 输出文件（相对题目目录） */\n   out: z.string().default('cover.png'),\n});\nexport type CoverGenerateOptions = z.output<typeof coverGenerateSchema>;\n\nexport const coverSchema = z.union([\n   z.object({ mode: z.literal('default') }),\n   z.object({\n      mode: z.literal('custom'),\n      /** 平台上的图片 id；`qpc cover --upload --write` 会把生成结果写回这里 */\n      imageId: z.string().min(1).optional(),\n      /** 配置了就能用 `qpc cover` 一键生成（后端题型必须自定义封面） */\n      generate: coverGenerateSchema.optional(),\n   }),\n]);\n\nexport const problemConfigSchema = z.object({\n   title: z.string().min(1, 'title 不能为空'),\n   /** 平台题目 id（qpc upload 返回的 pid）：填了它就在该题目下追加新版本，否则每次新建 */\n   problemId: z.number().int().positive().optional(),\n   /** 题型；缺省为前端，老题目不需要改配置 */\n   type: z.enum(PROBLEM_TYPES).default('frontend'),\n   /** 题面正文；与 detailFile 二选一 */\n   detail: z.string().min(1).optional(),\n   /** 题面文件（相对题目目录），便于把长题面单独放一个 markdown */\n   detailFile: z.string().min(1).optional(),\n   difficulty: z.enum(DIFFICULTIES),\n   tagIds: z\n      .array(z.number().int().positive())\n      .min(1, 'tagIds 至少需要一个标签（用 `qpc tag` 查看可用 id）'),\n   /** 留空表示\"以判题脚本里各检查点之和为准\"；填写则必须与之和相等 */\n   totalScore: z.number().int().positive().optional(),\n   cover: coverSchema.default({ mode: 'default' }),\n   runtime: z\n      .object({\n         /** 判题时打包上传的目录，同时决定快照挂载路径（快照键为 `/<judgeUploadPath>/...`） */\n         judgeUploadPath: z.string().min(1).default(DEFAULT_JUDGE_UPLOAD_PATH),\n         initCommand: z.string().min(1).default(DEFAULT_INIT_COMMAND),\n         buildCommand: z.string().min(1).optional(),\n         bootCommand: z.string().min(1).optional(),\n         /** 后端服务：初始镜像 id（不是 docker 镜像名，取值见 @challenge/shared/backend-service-image） */\n         serviceImage: z.enum(BACKEND_SERVICE_IMAGE_IDS).optional(),\n         /** 后端服务：服务监听端口（也是判题机请求的端口） */\n         servicePort: z.number().int().positive().max(65535).default(3000),\n      })\n      .default({\n         judgeUploadPath: DEFAULT_JUDGE_UPLOAD_PATH,\n         initCommand: DEFAULT_INIT_COMMAND,\n         servicePort: 3000,\n      }),\n   paths: z\n      .object({\n         template: z.string().min(1).default('template'),\n         answer: z.string().min(1).default('answer'),\n         judge: z.string().min(1).default('judge.js'),\n      })\n      .default({ template: 'template', answer: 'answer', judge: 'judge.js' }),\n});\n\nexport type ProblemConfigInput = z.input<typeof problemConfigSchema>;\nexport type ProblemConfig = z.output<typeof problemConfigSchema>;\n\n/** 后端题的镜像与 bootCommand 由镜像决定（覆盖作者写的值），initCommand 仅缺省时填默认值；回报被覆盖字段供 `qpc check` 提示。 */\nexport const applyBackendServiceImageDefaults = (\n   config: ProblemConfig,\n): { config: ProblemConfig; overridden: string[] } => {\n   if (config.type !== 'backend_service') {\n      return { config, overridden: [] };\n   }\n   const mountPath =\n      config.runtime.judgeUploadPath || DEFAULT_JUDGE_UPLOAD_PATH;\n   const serviceImage = normalizeBackendServiceImageId(\n      config.runtime.serviceImage,\n   );\n   const bootCommand = buildBackendBootCommand(serviceImage, mountPath);\n   const defaultInitCommand = buildBackendInitCommand(serviceImage, mountPath);\n\n   const overridden: string[] = [];\n   if (\n      config.runtime.bootCommand &&\n      config.runtime.bootCommand !== bootCommand\n   ) {\n      overridden.push('runtime.bootCommand');\n   }\n   // initCommand 的 schema 默认值是静态服务器命令（前端用），后端题没写时会落到它上面；\n   // 只有这种情况才用镜像默认值替掉它，作者写过的保留。\n   const initCommand =\n      !config.runtime.initCommand ||\n      config.runtime.initCommand === DEFAULT_INIT_COMMAND\n         ? defaultInitCommand\n         : config.runtime.initCommand;\n\n   return {\n      config: {\n         ...config,\n         runtime: {\n            ...config.runtime,\n            serviceImage,\n            servicePort:\n               config.runtime.servicePort ??\n               getBackendServiceDefaultPort(serviceImage),\n            bootCommand,\n            initCommand,\n         },\n      },\n      overridden,\n   };\n};\n","import { readFileSync } from 'node:fs';\n\nexport const CLI_NAME = 'qpc';\nexport const CLI_DESCRIPTION = 'Quanta 出题工具：脚手架、离线预检、上传与发布';\n\nconst readVersion = (): string => {\n   try {\n      const raw = readFileSync(\n         new URL('../package.json', import.meta.url),\n         'utf8',\n      );\n      const parsed = JSON.parse(raw) as { version?: string };\n      return parsed.version ?? '0.0.0';\n   } catch {\n      return '0.0.0';\n   }\n};\n\nexport const CLI_VERSION = readVersion();\n","/** 包的程序化入口（exports/main 指向这里）：零副作用，与 bin 入口分开以避免 jiti 加载配置时把 CLI 跑一遍；只依赖 problem-config-schema（纯 zod）。 */\nimport type { ProblemConfigInput } from './domain/problem-config-schema';\n\nexport type {\n   Difficulty,\n   ProblemConfig,\n   ProblemConfigInput,\n} from './domain/problem-config-schema';\nexport {\n   DEFAULT_INIT_COMMAND,\n   DEFAULT_JUDGE_UPLOAD_PATH,\n   DIFFICULTIES,\n   problemConfigSchema,\n} from './domain/problem-config-schema';\nexport type { Finding, Severity, ValidationReport } from './domain/validate';\nexport { CLI_NAME, CLI_VERSION } from './version';\n\n/** 出题配置的类型助手（运行时恒等函数）；返回值刻意声明为 ProblemConfigInput 而非泛型 T，让拼错的字段名触发多余属性检查。 */\nexport const defineProblemConfig = (\n   config: ProblemConfigInput,\n): ProblemConfigInput => config;\n"]}

package/package.json

@@ -1,6 +1,61 @@
 {
-  "name": "@quantacenter/quanta-problem-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+   "name": "@quantacenter/quanta-problem-cli",
+   "version": "1.0.1",
+   "description": "Quanta 出题工具链：脚手架、离线预检、上传与发布（qpc）",
+   "license": "ISC",
+   "repository": {
+      "type": "git",
+      "url": "git+https://github.com/QuantaCenter/quanta-challenge.git",
+      "directory": "packages/problem-creator-cli"
+   },
+   "publishConfig": {
+      "access": "public"
+   },
+   "type": "module",
+   "engines": {
+      "node": ">=20.11"
+   },
+   "bin": {
+      "qpc": "./dist/index.js"
+   },
+   "main": "./dist/program.js",
+   "types": "./dist/program.d.ts",
+   "exports": {
+      ".": {
+         "types": "./dist/program.d.ts",
+         "import": "./dist/program.js"
+      },
+      "./package.json": "./package.json"
+   },
+   "files": [
+      "dist",
+      "templates",
+      "README.md"
+   ],
+   "scripts": {
+      "dev": "tsx src/index.ts",
+      "build": "tsup",
+      "start": "node dist/index.js",
+      "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.examples.json",
+      "lint": "biome check .",
+      "lint:fix": "biome check --write .",
+      "format": "biome format --write .",
+      "verify": "pnpm lint && pnpm typecheck && pnpm build"
+   },
+   "dependencies": {
+      "@clack/prompts": "^1.8.1",
+      "commander": "^14.0.1",
+      "jiti": "^2.5.1",
+      "picocolors": "^1.1.1",
+      "sharp": "^0.34.3",
+      "zod": "^4.0.5"
+   },
+   "devDependencies": {
+      "@biomejs/biome": "^2.5.15",
+      "@challenge/shared": "workspace:^",
+      "@types/node": "^24.0.14",
+      "tsup": "^8.5.1",
+      "tsx": "^4.7.1",
+      "typescript": "^5.8.3"
+   }
+}

package/templates/backend_service/README.md

@@ -0,0 +1,55 @@
+# {{title}}
+
+本目录由 `qpc init --type backend_service` 生成：一道**后端服务题**的骨架。
+判题机不发浏览器请求，而是把参考答案跑起来、向它发 HTTP 请求做断言。
+
+## 目录结构
+
+```
+problem.config.ts   题目配置（题型、镜像、端口、启动命令）
+detail.md           题面（Markdown，原样展示给学生）
+judge.js            判题脚本（用 http 发请求、断言响应）
+template/           答案模板：学生起点（含 pnpm-lock.yaml）
+answer/             参考解：必须拿满分（含 pnpm-lock.yaml）
+cover.png           init 已按 cover.generate 渲染好的封面（还没上传）
+```
+
+## 标准流程
+
+```bash
+# 0. 后端题必须自定义封面：生成 → 上传 → 把 imageId 写回配置
+qpc cover --upload --write
+
+# 1. 本地预检（毫秒级，先挡掉静态错误）
+qpc check
+
+# 2. 上传并等待审计（生成题目版本，审计约 20 秒）
+qpc upload --wait
+
+# 3. 审计通过后发布
+qpc publish <problemId>
+```
+
+> 第 0 步之前 `qpc check` 会报 IMG001（custom 封面缺 imageId），这是预期的：
+> 后端题没有首屏可截图，封面只能先生成再上传。
+
+## 加依赖
+
+`template/` 与 `answer/` 是两份独立工程（学生改 template，判分跑 answer）。
+加了依赖要同步两边，并在**对应目录**重新生成锁文件——容器是断网离线安装，
+没有锁文件或者锁文件与 package.json 对不上都会起不来：
+
+```bash
+cd answer   && pnpm add express   # 同时更新 package.json 与 pnpm-lock.yaml
+cd ../template && pnpm add express
+```
+
+## 需要人工确认的事（预检覆盖不到）
+
+- [ ] 参考解真的能拿满分（看 `qpc upload --wait` 的检查点明细）
+- [ ] 答案模板明显低分（证明判题能抓错）
+- [ ] `initCommand` 指向的入口能启动，服务监听 `servicePort`（默认 3000）
+- [ ] 封面好看（后端题用的是 `cover.png` 生成的图，不是截图）
+
+完整链路与镜像约定见仓库 `docs/BACKEND_SERVICE_PROBLEM.md`；
+出题踩坑清单见 `docs/PROBLEM_AUTHORING.md`。

package/templates/backend_service/answer/package.json

@@ -0,0 +1,9 @@
+{
+   "name": "todo-api",
+   "version": "1.0.0",
+   "private": true,
+   "type": "module",
+   "scripts": {
+      "start": "node server.js"
+   }
+}

package/templates/backend_service/answer/pnpm-lock.yaml

@@ -0,0 +1,9 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .: {}

package/templates/backend_service/answer/server.js

@@ -0,0 +1,61 @@
+import { createServer } from 'node:http';
+
+// 参考解：零依赖的 node:http 服务；改完在 answer/ 跑 pnpm install --lockfile-only，让锁文件与 package.json 一致。
+const items = [];
+let nextId = 1;
+
+const sendJson = (res, status, body) => {
+   const payload = JSON.stringify(body);
+   res.writeHead(status, {
+      'content-type': 'application/json; charset=utf-8',
+      'content-length': Buffer.byteLength(payload),
+   });
+   res.end(payload);
+};
+
+const readJson = (req) =>
+   new Promise((resolve) => {
+      let raw = '';
+      req.on('data', (chunk) => {
+         raw += chunk;
+      });
+      req.on('end', () => {
+         try {
+            resolve(raw ? JSON.parse(raw) : {});
+         } catch {
+            resolve(undefined);
+         }
+      });
+   });
+
+const server = createServer(async (req, res) => {
+   const url = new URL(req.url ?? '/', 'http://localhost');
+
+   if (req.method === 'GET' && url.pathname === '/health') {
+      return sendJson(res, 200, { ok: true });
+   }
+
+   if (req.method === 'GET' && url.pathname === '/items') {
+      return sendJson(res, 200, { items });
+   }
+
+   if (req.method === 'POST' && url.pathname === '/items') {
+      const body = await readJson(req);
+      const title = typeof body?.title === 'string' ? body.title.trim() : '';
+      if (!title) {
+         return sendJson(res, 400, { error: 'title_required' });
+      }
+      const item = { id: nextId, title };
+      nextId += 1;
+      items.push(item);
+      return sendJson(res, 201, { item });
+   }
+
+   return sendJson(res, 404, { error: 'not_found' });
+});
+
+// 端口从环境变量注入：编辑器与判题容器都会传 PORT / QUANTA_PORT。
+const port = Number(process.env.PORT || process.env.QUANTA_PORT || 3000);
+server.listen(port, () => {
+   console.log('todo-api listening on ' + port);
+});

package/templates/backend_service/detail.md

@@ -0,0 +1,30 @@
+# {{title}}
+
+用 Node.js 写一个**待办清单 HTTP API**：进程必须监听 **3000** 端口，启动后对外提供下面的接口。
+
+> 本题不要求任何第三方依赖，用 Node 内置的 `node:http` 就够；想用 Express/Fastify
+> 也行，记得同步 `template/` 与 `answer/` 的依赖和锁文件（见 README）。
+
+## 接口要求
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/health` | 返回 `200` 与 `{ "ok": true }` |
+| GET | `/items` | 返回全部待办：`{ "items": [{ "id": 1, "title": "写题" }] }`，初始为空 |
+| POST | `/items` | 新建待办，请求体 `{ "title": "写题" }` |
+
+约定：
+
+- `POST /items` 成功返回 **201**，响应体为 `{ "item": { "id": 1, "title": "写题" } }`，`id` 从 `1` 开始自增。
+- `title` 为空或缺失时返回 **400**，且不创建。
+- 请求与响应都是 JSON。
+
+## 怎么自己验证
+
+判题机不发浏览器请求，只用 HTTP 断言。你可以在预览面板的终端里自己 curl：
+
+```bash
+curl -s localhost:3000/health
+curl -s -X POST localhost:3000/items -H 'content-type: application/json' -d '{"title":"写题"}'
+curl -s localhost:3000/items
+```

package/templates/backend_service/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+# qpc 的本地缓存（预检产物、审计快照）
+.qpc/
+.DS_Store

package/templates/backend_service/judge.js

@@ -0,0 +1,43 @@
+// 判题脚本必须写成 `export default defineTestHandler(...)`：判题机会把 "export default " 替换成 "const run = "；后端给的是 http，不是 page。
+export default defineTestHandler(async ({ http, $ }) => {
+   $.defineCheckPoint('GET /health 返回 ok', 5, async () => {
+      const res = await http.get('/health');
+      $.expect(res.status === 200, '期望 /health 返回 200，实际为 ' + res.status);
+      $.expect(
+         res.json && res.json.ok === true,
+         '期望 body.ok 为 true，实际为 ' + JSON.stringify(res.json)
+      );
+      return 5; // 必须 return 本检查点得分：不返回即使断言全过也记 0 分
+   });
+
+   $.defineCheckPoint('POST /items 创建一条待办', 10, async () => {
+      // body 传对象时会自动 JSON.stringify 并带上 content-type
+      const res = await http.post('/items', { title: '写题' });
+      $.expect(res.status === 201, '期望创建返回 201，实际为 ' + res.status);
+      const item = res.json && res.json.item;
+      $.expect(
+         item !== undefined,
+         '期望响应体里有 item，实际为 ' + JSON.stringify(res.json)
+      );
+      $.expect(
+         item && item.title === '写题',
+         '期望 item.title 为 "写题"，实际为 ' + (item && item.title)
+      );
+      return 10;
+   });
+
+   $.defineCheckPoint('GET /items 能读到刚创建的一条', 5, async () => {
+      const res = await http.get('/items');
+      $.expect(res.status === 200, '期望 /items 返回 200，实际为 ' + res.status);
+      const items = res.json && res.json.items;
+      $.expect(
+         Array.isArray(items),
+         '期望 body.items 是数组，实际为 ' + typeof items
+      );
+      $.expect(
+         Array.isArray(items) && items.length === 1 && items[0].title === '写题',
+         '期望只有 1 条 title 为 "写题" 的待办，实际为 ' + JSON.stringify(items)
+      );
+      return 5;
+   });
+});

package/templates/backend_service/problem.config.ts

@@ -0,0 +1,37 @@
+import { defineProblemConfig } from '@challenge/problem-creator-cli';
+
+// 后端服务题配置。字段语义与踩坑清单见 docs/BACKEND_SERVICE_PROBLEM.md
+export default defineProblemConfig({
+   title: '{{title}}',
+   type: 'backend_service',
+   // 题面单独放一个 markdown：后端题通常要列接口清单，写在配置里太长
+   detailFile: 'detail.md',
+   difficulty: '{{difficulty}}',
+   tagIds: [{{tagIds}}], // TODO: 换成后端相关的标签 id
+   // 后端题没有首屏可截图：init 已渲染 cover.png，跑 qpc cover --upload --write 上传并把 imageId 写回这里（否则 IMG001 拦下）。
+   cover: {
+      mode: 'custom',
+      generate: {
+         bg: '{{coverBg}}',
+         bgTo: '{{coverBgTo}}',
+         accent: '{{coverAccent}}',
+         subtitle: '{{coverSubtitle}}',
+      },
+   },
+   runtime: {
+      // 判题打包目录，同时决定快照键前缀（/project/...）
+      judgeUploadPath: '{{mountPath}}',
+      // 服务启动命令：编辑器与判题容器共用，入口写在 package.json 的 scripts.start
+      initCommand: '{{initCommand}}',
+      // 初始镜像（容器 + 语言运行时）；bootCommand 由镜像决定，不用手写
+      serviceImage: '{{serviceImage}}',
+      servicePort: {{servicePort}},
+      // 没有构建步骤也要填一个立即退出的命令，否则编辑器点"提交"会空转
+      buildCommand: 'node -e ""',
+   },
+   paths: {
+      template: 'template',
+      answer: 'answer',
+      judge: 'judge.js',
+   },
+});

package/templates/backend_service/template/package.json

@@ -0,0 +1,9 @@
+{
+   "name": "todo-api",
+   "version": "1.0.0",
+   "private": true,
+   "type": "module",
+   "scripts": {
+      "start": "node server.js"
+   }
+}