visual-prompt-kit 0.1.0

package/src/cli.js

@@ -0,0 +1,261 @@
+const {
+  listThemes,
+  getTheme,
+  listDimensions,
+  validateTheme,
+  generateTags,
+  serializeSelection,
+  buildPromptRequest,
+  serializePromptRequest
+} = require("./index");
+
+function writeLine(stream, message = "") {
+  stream.write(`${message}\n`);
+}
+
+function parseKeyValue(raw, optionName) {
+  const separator = raw.indexOf("=");
+  if (separator <= 0 || separator === raw.length - 1) {
+    throw new Error(`Option ${optionName} expects KEY=VALUE, received "${raw}".`);
+  }
+
+  return {
+    key: raw.slice(0, separator),
+    value: raw.slice(separator + 1)
+  };
+}
+
+function ensureNextValue(argv, index, optionName) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`Option ${optionName} requires a value.`);
+  }
+  return value;
+}
+
+function parseArgv(argv) {
+  const args = [...argv];
+  const first = args[0];
+  const command = !first || first.startsWith("-") ? "help" : args.shift();
+  const options = {
+    theme: "sweet-girl",
+    format: undefined,
+    seed: undefined,
+    preset: undefined,
+    locks: {},
+    counts: {}
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+
+    switch (token) {
+      case "--theme":
+      case "-t": {
+        options.theme = ensureNextValue(args, index, token);
+        index += 1;
+        break;
+      }
+      case "--seed":
+      case "-s": {
+        options.seed = ensureNextValue(args, index, token);
+        index += 1;
+        break;
+      }
+      case "--preset":
+      case "-p": {
+        options.preset = ensureNextValue(args, index, token);
+        index += 1;
+        break;
+      }
+      case "--format":
+      case "-f": {
+        options.format = ensureNextValue(args, index, token);
+        index += 1;
+        break;
+      }
+      case "--lock":
+      case "-l": {
+        const parsed = parseKeyValue(ensureNextValue(args, index, token), token);
+        options.locks[parsed.key] ||= [];
+        options.locks[parsed.key].push(parsed.value);
+        index += 1;
+        break;
+      }
+      case "--count":
+      case "-c": {
+        const parsed = parseKeyValue(ensureNextValue(args, index, token), token);
+        const count = Number(parsed.value);
+        if (!Number.isInteger(count) || count < 1) {
+          throw new Error(`Option ${token} requires a positive integer count.`);
+        }
+        options.counts[parsed.key] = count;
+        index += 1;
+        break;
+      }
+      case "--help":
+      case "-h": {
+        options.help = true;
+        break;
+      }
+      default:
+        throw new Error(`Unknown option "${token}".`);
+    }
+  }
+
+  return {
+    command,
+    options
+  };
+}
+
+function formatList(items, format) {
+  if (format === "json") {
+    return JSON.stringify(items, null, 2);
+  }
+
+  if (format === "txt" || format === "text") {
+    return items.join("\n");
+  }
+
+  throw new Error(`Unsupported list format "${format}".`);
+}
+
+function printHelp(stdout) {
+  writeLine(stdout, "visual-prompt <command> [options]");
+  writeLine(stdout);
+  writeLine(stdout, "Commands:");
+  writeLine(stdout, "  themes                              List theme ids");
+  writeLine(stdout, "  dimensions [--theme <id>]           List dimension keys for a theme");
+  writeLine(stdout, "  presets [--theme <id>]              List preset names for a theme");
+  writeLine(stdout, "  validate [--theme <id>]             Validate a theme");
+  writeLine(stdout, "  generate [options]                  Generate prompt tags");
+  writeLine(stdout, "  prompt [options]                    Build an LLM prompt from generated tags");
+  writeLine(stdout);
+  writeLine(stdout, "Shared options for generate / prompt:");
+  writeLine(stdout, "  --theme, -t   <id>                  Theme id, default sweet-girl");
+  writeLine(stdout, "  --seed, -s    <value>               Stable random seed");
+  writeLine(stdout, "  --preset, -p  <name>                Apply a preset");
+  writeLine(stdout, "  --format, -f  <json|txt>            Output format");
+  writeLine(stdout, "  --lock, -l    <dimension=text>      Repeatable lock option");
+  writeLine(stdout, "  --count, -c   <dimension=n>         Override pick count");
+}
+
+function resolveFormat(command, format) {
+  if (format) {
+    return format;
+  }
+
+  if (command === "generate") {
+    return "json";
+  }
+
+  if (command === "prompt") {
+    return "txt";
+  }
+
+  return "txt";
+}
+
+function runCli(argv, io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+
+  try {
+    const { command, options } = parseArgv(argv);
+    const format = resolveFormat(command, options.format);
+
+    if (options.help || command === "help") {
+      printHelp(stdout);
+      return 0;
+    }
+
+    if (command === "themes") {
+      writeLine(stdout, formatList(listThemes().map((theme) => theme.id), format));
+      return 0;
+    }
+
+    const theme = getTheme(options.theme);
+
+    if (command === "dimensions") {
+      writeLine(
+        stdout,
+        formatList(listDimensions(theme).map((dimension) => dimension.key), format)
+      );
+      return 0;
+    }
+
+    if (command === "presets") {
+      writeLine(stdout, formatList(Object.keys(theme.presets), format));
+      return 0;
+    }
+
+    if (command === "validate") {
+      const result = validateTheme(theme);
+      if (format === "json") {
+        writeLine(
+          stdout,
+          JSON.stringify(
+            {
+              theme: theme.id,
+              valid: result.valid,
+              warnings: result.warnings,
+              errors: result.errors
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        for (const warning of result.warnings) {
+          writeLine(stderr, `WARN: ${warning}`);
+        }
+
+        if (!result.valid) {
+          for (const error of result.errors) {
+            writeLine(stderr, `ERROR: ${error}`);
+          }
+        } else {
+          writeLine(stdout, `Theme "${theme.id}" passed validation with ${theme.dimensions.length} dimensions.`);
+        }
+      }
+
+      return result.valid ? 0 : 1;
+    }
+
+    if (command === "generate") {
+      const result = generateTags({
+        theme,
+        seed: options.seed,
+        preset: options.preset,
+        locks: options.locks,
+        counts: options.counts
+      });
+
+      writeLine(stdout, serializeSelection(result, format));
+      return 0;
+    }
+
+    if (command === "prompt") {
+      const request = buildPromptRequest({
+        theme,
+        seed: options.seed,
+        preset: options.preset,
+        locks: options.locks,
+        counts: options.counts
+      });
+
+      writeLine(stdout, serializePromptRequest(request, format));
+      return 0;
+    }
+
+    throw new Error(`Unknown command "${command}".`);
+  } catch (error) {
+    writeLine(stderr, error.message);
+    return 1;
+  }
+}
+
+module.exports = {
+  runCli
+};

package/src/define.js

@@ -0,0 +1,78 @@
+function normalizeItem(key, item, index) {
+  if (typeof item === "string") {
+    return {
+      id: `${key}-${String(index + 1).padStart(3, "0")}`,
+      text: item,
+      weight: 1
+    };
+  }
+
+  return {
+    id: item.id || `${key}-${String(index + 1).padStart(3, "0")}`,
+    text: item.text,
+    weight: item.weight || 1,
+    tags: item.tags || [],
+    bannedWith: item.bannedWith || []
+  };
+}
+
+function defineDimension(definition) {
+  if (!definition || !definition.key) {
+    throw new Error("Dimension definition requires a key.");
+  }
+
+  if (!Array.isArray(definition.items) || definition.items.length === 0) {
+    throw new Error(`Dimension "${definition.key}" must define a non-empty items array.`);
+  }
+
+  const items = definition.items.map((item, index) => normalizeItem(definition.key, item, index));
+
+  return Object.freeze({
+    key: definition.key,
+    zhName: definition.zhName,
+    description: definition.description || "",
+    pick: Object.freeze({
+      min: definition.pick?.min ?? 1,
+      max: definition.pick?.max ?? 1,
+      recommended: definition.pick?.recommended ?? definition.pick?.min ?? 1
+    }),
+    rules: Object.freeze([...(definition.rules || [])]),
+    minimumItems: definition.minimumItems ?? 20,
+    forbiddenTerms: Object.freeze([...(definition.forbiddenTerms || [])]),
+    items: Object.freeze(items)
+  });
+}
+
+function defineTheme(definition) {
+  if (!definition || !definition.id) {
+    throw new Error("Theme definition requires an id.");
+  }
+
+  if (!Array.isArray(definition.dimensions) || definition.dimensions.length === 0) {
+    throw new Error(`Theme "${definition.id}" must define dimensions.`);
+  }
+
+  const seen = new Set();
+  for (const dimension of definition.dimensions) {
+    if (seen.has(dimension.key)) {
+      throw new Error(`Duplicate dimension key "${dimension.key}" in theme "${definition.id}".`);
+    }
+    seen.add(dimension.key);
+  }
+
+  return Object.freeze({
+    id: definition.id,
+    version: definition.version || "0.1.0",
+    locale: definition.locale || "zh-CN",
+    target: definition.target,
+    description: definition.description || "",
+    bannedLexicon: Object.freeze([...(definition.bannedLexicon || [])]),
+    presets: Object.freeze({ ...(definition.presets || {}) }),
+    dimensions: Object.freeze([...definition.dimensions])
+  });
+}
+
+module.exports = {
+  defineDimension,
+  defineTheme
+};

package/src/generator/export.js

@@ -0,0 +1,20 @@
+function flattenSelection(tags) {
+  return Object.values(tags).flat();
+}
+
+function serializeSelection(result, format = "json") {
+  if (format === "txt") {
+    return result.flat.join("，");
+  }
+
+  if (format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+
+  throw new Error(`Unsupported export format "${format}".`);
+}
+
+module.exports = {
+  flattenSelection,
+  serializeSelection
+};

package/src/generator/generateTags.js

@@ -0,0 +1,64 @@
+const { createSeededRandom } = require("./seed");
+const { pickWeightedUnique } = require("./pick");
+const { mergeLocks } = require("./locks");
+const { flattenSelection } = require("./export");
+
+function findItemsByText(dimension, texts) {
+  return texts.map((text) => {
+    const item = dimension.items.find((entry) => entry.text === text);
+    if (!item) {
+      throw new Error(`Unknown keyword "${text}" in dimension "${dimension.key}".`);
+    }
+    return item;
+  });
+}
+
+function generateTags(options) {
+  const theme = options.theme;
+  const seed = options.seed ?? `seed-${Date.now()}`;
+  const preset = options.preset ?? null;
+  const counts = options.counts || {};
+  const mergedLocks = mergeLocks(theme, preset, options.locks || {});
+  const rng = createSeededRandom(seed);
+  const tags = {};
+  const detailed = {};
+
+  for (const dimension of theme.dimensions) {
+    const lockedTexts = mergedLocks[dimension.key] || [];
+    const lockedItems = findItemsByText(dimension, lockedTexts);
+    if (lockedItems.length > dimension.pick.max) {
+      throw new Error(
+        `Locked keyword count for "${dimension.key}" exceeds max pick count ${dimension.pick.max}.`
+      );
+    }
+    const lockedIds = new Set(lockedItems.map((item) => item.id));
+    const requestedCount = counts[dimension.key] ?? dimension.pick.recommended;
+    const finalCount = Math.max(
+      dimension.pick.min,
+      Math.min(dimension.pick.max, Math.max(requestedCount, lockedItems.length))
+    );
+    const picks = pickWeightedUnique(
+      dimension.items,
+      finalCount - lockedItems.length,
+      rng,
+      lockedIds
+    );
+    const selected = [...lockedItems, ...picks];
+
+    tags[dimension.key] = selected.map((item) => item.text);
+    detailed[dimension.key] = selected;
+  }
+
+  return {
+    theme: theme.id,
+    seed,
+    preset,
+    tags,
+    detailed,
+    flat: flattenSelection(tags)
+  };
+}
+
+module.exports = {
+  generateTags
+};

package/src/generator/index.js

@@ -0,0 +1,8 @@
+const { generateTags } = require("./generateTags");
+const { flattenSelection, serializeSelection } = require("./export");
+
+module.exports = {
+  generateTags,
+  flattenSelection,
+  serializeSelection
+};

package/src/generator/locks.js

@@ -0,0 +1,40 @@
+function dedupe(values) {
+  return [...new Set(values)];
+}
+
+function resolvePreset(theme, presetName) {
+  if (!presetName) {
+    return {};
+  }
+
+  const preset = theme.presets[presetName];
+  if (!preset) {
+    throw new Error(`Unknown preset "${presetName}" for theme "${theme.id}".`);
+  }
+
+  return preset;
+}
+
+function mergeLocks(theme, presetName, explicitLocks = {}) {
+  const presetLocks = resolvePreset(theme, presetName);
+  const keys = new Set([
+    ...Object.keys(presetLocks),
+    ...Object.keys(explicitLocks)
+  ]);
+
+  const merged = {};
+
+  for (const key of keys) {
+    merged[key] = dedupe([
+      ...(presetLocks[key] || []),
+      ...(explicitLocks[key] || [])
+    ]);
+  }
+
+  return merged;
+}
+
+module.exports = {
+  mergeLocks,
+  resolvePreset
+};

package/src/generator/pick.js

@@ -0,0 +1,27 @@
+function pickWeightedUnique(items, count, rng, excludedIds = new Set()) {
+  const pool = items.filter((item) => !excludedIds.has(item.id));
+  const selected = [];
+
+  while (selected.length < count && pool.length > 0) {
+    const totalWeight = pool.reduce((sum, item) => sum + (item.weight || 1), 0);
+    let threshold = rng() * totalWeight;
+    let pickedIndex = 0;
+
+    for (let index = 0; index < pool.length; index += 1) {
+      threshold -= pool[index].weight || 1;
+      if (threshold <= 0) {
+        pickedIndex = index;
+        break;
+      }
+    }
+
+    selected.push(pool[pickedIndex]);
+    pool.splice(pickedIndex, 1);
+  }
+
+  return selected;
+}
+
+module.exports = {
+  pickWeightedUnique
+};

package/src/generator/seed.js

@@ -0,0 +1,28 @@
+function hashSeed(input) {
+  const text = String(input);
+  let hash = 2166136261;
+
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+
+  return hash >>> 0;
+}
+
+function createSeededRandom(seed) {
+  let state = hashSeed(seed);
+
+  return function next() {
+    state += 0x6D2B79F5;
+    let value = state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+module.exports = {
+  hashSeed,
+  createSeededRandom
+};

package/src/index.js

@@ -0,0 +1,23 @@
+const { defineDimension, defineTheme } = require("./define");
+const { themes, listThemes, getTheme, listDimensions, getDimension } = require("./themes");
+const sweetGirl = require("./themes/sweet-girl");
+const { validateTheme } = require("./validate");
+const { generateTags, flattenSelection, serializeSelection } = require("./generator");
+const { buildPromptRequest, serializePromptRequest } = require("./prompt");
+
+module.exports = {
+  defineDimension,
+  defineTheme,
+  themes,
+  sweetGirl,
+  listThemes,
+  getTheme,
+  listDimensions,
+  getDimension,
+  validateTheme,
+  generateTags,
+  flattenSelection,
+  serializeSelection,
+  buildPromptRequest,
+  serializePromptRequest
+};

package/src/prompt/buildPromptRequest.js

@@ -0,0 +1,63 @@
+const { generateTags } = require("../generator");
+
+const DEFAULT_SYSTEM_PROMPT = [
+  "你是通用生图模型的人像提示词编辑器。",
+  "把离散视觉标签重组为一段自然完整的中文生图提示词，适用于 Google、豆包等常见生图模型。",
+  "你必须围绕甜美少女写真，吸收全部标签并重组为具体、连贯、有画面感的描述。",
+  "禁止罗列标签，禁止按原顺序复述，禁止使用“采用、呈现、营造”等机械拼接句。"
+].join("");
+
+function formatDimensionTags(tags) {
+  return Object.entries(tags)
+    .map(([key, values]) => `- ${key}: ${values.join(" / ")}`)
+    .join("\n");
+}
+
+function buildPromptRequest(options) {
+  const theme = options.theme;
+  const selection =
+    options.selection ||
+    generateTags({
+      theme,
+      seed: options.seed,
+      preset: options.preset,
+      locks: options.locks,
+      counts: options.counts
+    });
+
+  const system = options.systemPrompt || DEFAULT_SYSTEM_PROMPT;
+  const user = [
+    "请把下面这些视觉标签无损重组为最终生图提示词。",
+    "",
+    "要求：",
+    "1. 必须吸收全部标签，但允许等价改写，不要逐词照抄。",
+    "2. 先建立主体、场景与核心氛围，再自然融入姿态、神情、光线、镜头和质感，形成完整画面。",
+    "3. 不要按输入顺序机械串联，不要写成标签清单扩写；如果读起来像顺序拼接，视为失败。",
+    "4. 可以补足少量合理细节，如发丝、肤感、空气感、空间层次，但不得新增冲突设定。",
+    "5. 语言应简洁、具体、可视化，适合常见通用生图模型理解。",
+    "6. 只输出一段中文提示词，建议 80 到 140 字，不要解释，不要分点，不要标题。",
+    "",
+    "按维度整理的视觉标签：",
+    formatDimensionTags(selection.tags),
+    "",
+    "请直接输出最终提示词。"
+  ].join("\n");
+
+  return {
+    theme: theme.id,
+    seed: selection.seed,
+    preset: selection.preset,
+    system,
+    user,
+    tags: selection.tags,
+    flat: selection.flat,
+    messages: [
+      { role: "system", content: system },
+      { role: "user", content: user }
+    ]
+  };
+}
+
+module.exports = {
+  buildPromptRequest
+};

package/src/prompt/index.js

@@ -0,0 +1,7 @@
+const { buildPromptRequest } = require("./buildPromptRequest");
+const { serializePromptRequest } = require("./serializePromptRequest");
+
+module.exports = {
+  buildPromptRequest,
+  serializePromptRequest
+};

package/src/prompt/serializePromptRequest.js

@@ -0,0 +1,21 @@
+function serializePromptRequest(request, format = "txt") {
+  if (format === "json") {
+    return JSON.stringify(request, null, 2);
+  }
+
+  if (format === "txt" || format === "text") {
+    return [
+      "[System Prompt]",
+      request.system,
+      "",
+      "[User Prompt]",
+      request.user
+    ].join("\n");
+  }
+
+  throw new Error(`Unsupported prompt format "${format}".`);
+}
+
+module.exports = {
+  serializePromptRequest
+};

package/src/themes/index.js

@@ -0,0 +1,43 @@
+const sweetGirl = require("./sweet-girl");
+
+const themes = {
+  [sweetGirl.id]: sweetGirl
+};
+
+function listThemes() {
+  return Object.values(themes);
+}
+
+function getTheme(themeId) {
+  const theme = themes[themeId];
+
+  if (!theme) {
+    throw new Error(`Unknown theme "${themeId}".`);
+  }
+
+  return theme;
+}
+
+function listDimensions(themeOrId) {
+  const theme = typeof themeOrId === "string" ? getTheme(themeOrId) : themeOrId;
+  return [...theme.dimensions];
+}
+
+function getDimension(themeOrId, dimensionKey) {
+  const theme = typeof themeOrId === "string" ? getTheme(themeOrId) : themeOrId;
+  const dimension = theme.dimensions.find((entry) => entry.key === dimensionKey);
+
+  if (!dimension) {
+    throw new Error(`Unknown dimension "${dimensionKey}" in theme "${theme.id}".`);
+  }
+
+  return dimension;
+}
+
+module.exports = {
+  themes,
+  listThemes,
+  getTheme,
+  listDimensions,
+  getDimension
+};