visual-prompt-kit 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# visual-prompt-kit
+
+面向图像生成工作流的结构化提示词 toolkit。
+
+## 目标
+
+- 所有内容统一服务于 **甜美少女摄影**。
+- 每个维度都保持 **短词、解耦、可随机拼装**。
+- 第一阶段负责生成结构化关键词。
+- 第二阶段负责给 AI 一段重组指令，把关键词写成适合 Google、豆包等通用生图模型理解的最终提示词。
+
+维护者如果要新增或修改关键词，直接看 [docs/keyword-authoring.md](./docs/keyword-authoring.md)。
+
+## 当前主题
+
+目前内置 1 个主题：
+
+- `sweet-girl`
+
+它包含 10 个维度：
+
+- `scene`
+- `expression`
+- `lighting`
+- `style`
+- `vibe`
+- `facial`
+- `subject`
+- `outfit`
+- `pose`
+- `camera`
+
+## 目录结构
+
+```text
+photo_skills/
+  package.json
+  README.md
+  docs/
+    keyword-authoring.md
+  skills/
+    image-prompt-composer/
+      SKILL.md
+  bin/
+    visual-prompt.js
+  src/
+    index.js
+    cli.js
+    define.js
+    generator/
+      export.js
+      generateTags.js
+      locks.js
+      pick.js
+      seed.js
+    prompt/
+      buildPromptRequest.js
+      index.js
+      serializePromptRequest.js
+    validate/
+      index.js
+      rules.js
+      theme.js
+    themes/
+      index.js
+      sweet-girl/
+        index.js
+        manifest.js
+        presets/
+          index.js
+        dimensions/
+          scene.js
+          expression.js
+          lighting.js
+          style.js
+          vibe.js
+          facial.js
+          subject.js
+          outfit.js
+          pose.js
+          camera.js
+  test/
+    cli.test.js
+    prompt.test.js
+    theme.test.js
+```
+
+## 两阶段工作流
+
+推荐按两阶段使用：
+
+1. 第一阶段：生成视觉骨架关键词。
+2. 第二阶段：输出给 AI 的重组指令，让 AI 把这些关键词写成适合通用生图模型理解的最终生图提示词。
+
+对应关系：
+
+- `generate` / `generateTags()`：生成关键词
+- `prompt` / `buildPromptRequest()`：生成给 AI 的重组指令
+
+## 对外 API
+
+包的主入口在 `src/index.js`。
+
+当前暴露的核心 API：
+
+- `getTheme(themeId)`
+- `listThemes()`
+- `listDimensions(themeOrId)`
+- `getDimension(themeOrId, dimensionKey)`
+- `validateTheme(theme)`
+- `generateTags(options)`
+- `buildPromptRequest(options)`
+- `flattenSelection(tags)`
+- `serializeSelection(result, format)`
+- `serializePromptRequest(request, format)`
+
+## 使用示例
+
+### 第一阶段：生成关键词
+
+```js
+const { getTheme, generateTags } = require("./src");
+
+const result = generateTags({
+  theme: getTheme("sweet-girl"),
+  seed: "2026-03-28",
+  preset: "campus",
+  locks: {
+    scene: ["樱花步道"],
+    vibe: ["校园心动感"]
+  }
+});
+
+console.log(result.tags);
+console.log(result.flat);
+```
+
+### 第二阶段：生成给 AI 的重组指令
+
+```js
+const { getTheme, generateTags, buildPromptRequest } = require("./src");
+
+const selection = generateTags({
+  theme: getTheme("sweet-girl"),
+  seed: "2026-03-28",
+  preset: "flowerhouse"
+});
+
+const request = buildPromptRequest({
+  theme: getTheme("sweet-girl"),
+  selection
+});
+
+console.log(request.system);
+console.log(request.user);
+```
+
+你可以把 `request.system` 和 `request.user` 直接喂给外部 AI，让它输出适合 Google、豆包等常见模型理解的最终生图提示词。
+
+## Preset
+
+当前内置 4 个 preset：
+
+- `campus`
+- `beach`
+- `bedroom`
+- `flowerhouse`
+
+## 校验规则
+
+`validateTheme(theme)` 当前会检查：
+
+- 维度 key 是否重复
+- 词条是否为空
+- 维度内是否有重复词
+- 词条长度是否超标
+- 是否命中主题禁词
+- 词库规模是否低于推荐阈值
+
+## 命令
+
+在 `photo_skills/` 目录下可直接运行：
+
+```bash
+npm test
+npm run validate
+npm run sample -- --seed sample-seed --preset beach
+npm run prompt -- --seed sample-seed --preset campus
+```
+
+## 安装后 Bin 使用示例
+
+本地开发阶段，先在包目录执行：
+
+```bash
+cd photo_skills
+npm link
+```
+
+完成后即可直接调用：
+
+```bash
+visual-prompt themes
+visual-prompt dimensions --theme sweet-girl
+visual-prompt presets --theme sweet-girl
+visual-prompt validate --theme sweet-girl
+visual-prompt generate --theme sweet-girl --preset campus --seed 2026-03-28
+visual-prompt generate --theme sweet-girl --preset beach --lock scene=海边栈桥 --format txt
+visual-prompt prompt --theme sweet-girl --preset campus --seed 2026-03-28
+visual-prompt prompt --theme sweet-girl --preset flowerhouse --lock scene=白色花房 --format txt
+```
+
+如果不想全局链接，而是在其他项目里按本地包安装，也可以这样：
+
+```bash
+npm install ../photo_skills
+npx visual-prompt themes
+npx visual-prompt generate --theme sweet-girl --preset bedroom --format txt
+npx visual-prompt prompt --theme sweet-girl --preset bedroom
+```
+
+## CLI 命令
+
+当前 CLI 支持：
+
+- `themes`
+- `dimensions`
+- `presets`
+- `validate`
+- `generate`
+- `prompt`
+
+CLI 关键参数：
+
+- `--theme, -t`
+- `--preset, -p`
+- `--seed, -s`
+- `--format, -f`
+- `--lock, -l`
+- `--count, -c`
+
+默认输出策略：
+
+- `generate` 默认输出 `json`
+- `prompt` 默认输出 `txt`
+- `themes` / `dimensions` / `presets` / `validate` 默认输出文本
+
+## Skill 封装
+
+项目内提供了一个通用 Agent Skills 兼容 skill：
+
+- `skills/image-prompt-composer`
+
+这个 skill 的职责不是重复实现生成逻辑，而是教代理如何调用 `visual-prompt generate` 和 `visual-prompt prompt`。它适合给 OpenClaw、Claude 或 Codex 这类支持 `SKILL.md` 的环境复用。

package/bin/visual-prompt.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../src/cli");
+
+process.exitCode = runCli(process.argv.slice(2));

package/docs/keyword-authoring.md

@@ -0,0 +1,207 @@
+# 关键词编写规范
+
+这份文档面向维护者，说明如何为 `visual-prompt-kit` 添加或修改关键词。
+
+## 总原则
+
+- 所有关键词都必须服务 **甜美少女摄影**。
+- 优先写 **短词**，不要写句子。
+- 优先写 **可拼装名词**，不要写完整叙事。
+- 一个词只负责一个维度，不要跨维度越界。
+- 能写客观场景或特征，就不要写主观评价。
+
+## 基本判断标准
+
+好的关键词通常满足这几条：
+
+- 一眼能看出属于哪个维度。
+- 单独拿出来就能被 AI 理解成稳定视觉信息。
+- 和其他维度随机组合时，不容易打架。
+- 没有多余修饰词，没有因果句，没有故事句。
+
+坏的关键词通常有这些问题：
+
+- 太长，像一句描述文案。
+- 同时包含场景、人物、动作、情绪多个维度。
+- 带明显价值判断，比如“绝美”“高级”“氛围感拉满”。
+- 带非主题方向，比如病态、惊悚、战损、赛博、末日。
+
+## 维度边界
+
+### `scene`
+
+- 只写地点、环境、空间。
+- 可以写风景名胜、旅游景点、抽象场域。
+- 不要写光线、镜头、人物状态。
+
+示例：
+
+- 好：`樱花步道`
+- 好：`雪山观景台`
+- 好：`镜面盐湖`
+- 差：`阳光洒满的樱花步道上`
+- 差：`少女站在樱花树下`
+
+### `expression`
+
+- 只写神态、眼神、嘴角、细小表情动作。
+- 不要写身体姿势、服饰、镜头。
+
+示例：
+
+- 好：`月牙笑眼`
+- 好：`低眸偷笑`
+- 差：`抱膝低头偷笑`
+
+### `lighting`
+
+- 只写光影和色调。
+- 不要写介质、镜头、场景。
+
+示例：
+
+- 好：`奶油逆光`
+- 好：`樱花粉色调`
+- 差：`胶片感夕阳逆光海边`
+
+### `style`
+
+- 只写成像介质、画质、风格质感。
+- 不要写情绪、场景、主体身份。
+
+示例：
+
+- 好：`富士400H胶片`
+- 好：`日杂写真质感`
+- 差：`海边少女胶片感`
+
+### `vibe`
+
+- 只写抽象氛围。
+- 不要写地点、动作、服装。
+
+示例：
+
+- 好：`元气初恋感`
+- 好：`海风轻甜感`
+- 差：`海边散步的初恋感`
+
+### `facial`
+
+- 只写五官比例、骨相、皮肤细节。
+- 不要写表情、妆容、情绪。
+
+示例：
+
+- 好：`幼态圆脸`
+- 好：`清透原生肌`
+- 差：`委屈小圆脸`
+
+### `subject`
+
+- 只写主体身份、气质、发型发质。
+- 不要写穿搭、场景、表情。
+
+示例：
+
+- 好：`甜妹大学生`
+- 好：`高马尾`
+- 差：`穿JK的高马尾学妹`
+
+### `outfit`
+
+- 只写服装和配饰。
+- 不要写人设、姿势、氛围。
+
+示例：
+
+- 好：`奶油白针织开衫`
+- 好：`珍珠耳钉`
+- 差：`学院风甜妹针织开衫`
+
+### `pose`
+
+- 只写身体姿势。
+- 不要写表情、场景、镜头。
+
+示例：
+
+- 好：`双膝并拢侧坐`
+- 好：`轻步前行`
+- 差：`海边回眸轻步前行`
+
+### `camera`
+
+- 只写景别、机位、镜头、构图。
+- 不要写情绪和环境内容。
+
+示例：
+
+- 好：`85mm人像镜头`
+- 好：`居中对称构图`
+- 差：`梦幻海边广角构图`
+
+## 写法要求
+
+- 尽量控制在短词级别。
+- 优先 2 到 8 个汉字，必要时可以稍长，但不要写成长句。
+- 不要使用“的、在、里、旁边、上面、正在”把词条写成句子。
+- 不要加入时间、动作、人物关系，除非该维度必须表达。
+- 不要堆多个限定词，能压缩就压缩。
+
+示例：
+
+- 差：`阳光透过香樟树的校园林荫道`
+- 好：`校园林荫道`
+
+- 差：`图书馆阳光最好的靠窗自习位`
+- 好：`图书馆窗边`
+
+- 差：`散发着面包香的烘焙坊橱窗外`
+- 好：`烘焙坊橱窗`
+
+## 添加关键词的流程
+
+1. 先确认关键词属于哪个维度。
+2. 写成最短可用版本。
+3. 检查是否和现有词重复或高度近似。
+4. 检查是否混入别的维度信息。
+5. 保存后运行校验。
+
+命令：
+
+```bash
+npm run validate
+npm test
+```
+
+如果只是想先观察当前主题内容，也可以执行：
+
+```bash
+visual-prompt dimensions --theme sweet-girl
+visual-prompt presets --theme sweet-girl
+visual-prompt generate --theme sweet-girl --preset campus --format txt
+```
+
+## 新增关键词时优先扩充的方向
+
+`scene` 维度优先补这些方向：
+
+- 风景名胜
+- 旅游景点
+- 异域街区
+- 山海湖川
+- 旅馆民宿
+- 抽象梦境场域
+- 童话幻想空间
+
+但即便扩这些方向，也要继续保持短词。
+
+## 提交前检查清单
+
+- 关键词是否仍然服务甜美少女摄影。
+- 是否是短词，而不是一句描述。
+- 是否只属于一个维度。
+- 是否没有和现有词重复。
+- 是否没有命中禁词。
+- 是否通过 `npm run validate`。

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "visual-prompt-kit",
+  "version": "0.1.0",
+  "description": "Composable visual prompt toolkit for image generation workflows.",
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/loulin/visual-prompt-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/loulin/visual-prompt-kit/issues"
+  },
+  "homepage": "https://github.com/loulin/visual-prompt-kit#readme",
+  "bin": {
+    "visual-prompt": "bin/visual-prompt.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./themes/sweet-girl": "./src/themes/sweet-girl/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "skills",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "validate": "node ./bin/visual-prompt.js validate --theme sweet-girl",
+    "sample": "node ./bin/visual-prompt.js generate --theme sweet-girl",
+    "prompt": "node ./bin/visual-prompt.js prompt --theme sweet-girl"
+  },
+  "keywords": [
+    "ai",
+    "prompt",
+    "photography",
+    "keywords",
+    "sweet-girl"
+  ],
+  "license": "UNLICENSED"
+}

package/skills/image-prompt-composer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: image-prompt-composer
+description: Generate structured image-prompt keywords and second-stage prompt requests with visual-prompt-kit. Use when the user wants themed image prompt brainstorming, keyword expansion, sweet-girl photography prompts, or a two-stage workflow that first generates tags and then asks another AI to compose the final prompt.
+---
+
+# Image Prompt Composer
+
+Use this skill when the user wants image-generation prompt help that should be grounded in the local `visual-prompt-kit` toolkit instead of improvised by hand.
+
+## Use
+
+- Use `generate` when the user wants keyword skeletons, themes, presets, locks, or structured visual tags.
+- Use `prompt` when the user wants the second-stage instruction that another AI should use to compose the final image prompt.
+- If the user wants the final prompt text directly, first obtain the prompt request, then synthesize the final prompt in the current conversation.
+
+## Workflow
+
+1. Identify the target theme, preset, locks, and output format.
+2. Prefer the local CLI:
+   `visual-prompt <command> ...`
+3. If the CLI is not installed globally but you are inside this repo, use:
+   `node ./bin/visual-prompt.js <command> ...`
+4. If neither is available, explain that `visual-prompt-kit` must be installed or linked before deterministic generation can run.
+
+## Core Commands
+
+```bash
+visual-prompt themes
+visual-prompt dimensions --theme sweet-girl
+visual-prompt presets --theme sweet-girl
+visual-prompt generate --theme sweet-girl --preset campus --format txt
+visual-prompt prompt --theme sweet-girl --preset campus
+```
+
+## Output Rules
+
+- Do not manually rewrite the toolkit's keywords unless the user explicitly asks you to edit or curate them.
+- Do not invent extra dimensions or presets that are not in the toolkit.
+- When returning generated tags, preserve the toolkit output unless the user asks for formatting changes.
+- When returning a final prompt, absorb all selected tags and avoid obvious sequential tag stitching.

package/skills/image-prompt-composer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Image Prompt Composer"
+  short_description: "Generate structured image prompt workflows"
+  default_prompt: "Use $image-prompt-composer to generate keywords and a second-stage image prompt request."