# Visual Reverse Engineer
跨工具通用的 **Agent Skills**——把图片或视频反向拆解成结构化的视觉描述,再重构出可复现原始视觉效果的提示词。
写一次,Claude Code / Codex / Cursor / Qoder / WorkBuddy / GitHub Copilot / Gemini CLI / Windsurf 都能用。
---
## 包含的技能
| 技能 | 输入 | 输出 | 适用场景 |
| --- | --- | --- | --- |
| [`visual-reverse-engineer`](skills/visual-reverse-engineer/) | 图片**或视频** | VISUAL DNA + 图片/视频 Prompt + Negative Prompt | 视频反推、一致性锁定、负面词 |
| [`image-reverse-analyst`](skills/image-reverse-analyst/) | **只做图片** | 风格分析 + 中文提示词 + 全英文 JSON | 要结构化 JSON、要风格分析 |
**怎么选:**
- 要 **JSON**、要**风格分析**、只处理图片 → `image-reverse-analyst`
- 要 **视频反推**、要 **REFERENCE LOCK MODE**、要 **Negative Prompt** → `visual-reverse-engineer`
两个技能可以同时安装,按各自的 description 自动触发。
---
## 它解决什么问题
看到一张很喜欢的图,想让 AI 生成同款——但不知道该写什么提示词。
普通做法是让模型"描述这张图",得到"一个女孩站在窗边,光线很柔和"——这种描述没用,生成出来完全不像。
本仓库的技能做法是**反推生成参数**:
```
85mm 中长焦 · f/4–f/5.6 · 硬光来自右前 45° · 主体压左三分线占高 70%
· 无缝深红背景纸 · 4:5 竖版 · 硬边阴影 · 暖肤色对冷红背景
```
### 核心区别
| 普通描述器 | 本仓库 |
| --- | --- |
| 回答「看到了什么」 | 回答「这张画面是如何生成的」 |
| 参数随口编 | 焦段/光圈/灯位一律标 `[inferred]` / `INFERRED` 并给出推测依据 |
| 直接给 Prompt | 先建分析结构,再从结构推导 Prompt |
| Negative 套固定词串 | 按参考图实际风险点动态生成 |
| 编造图上不存在的文字 | 看不清标 `UNCERTAIN`,没有就填 `"None"` |
---
## 安装
三种方式,任选其一。
### 方式一:skills CLI(推荐)
```bash
npx skills add <sundny8>/visual-reverse-engineer
```
非交互式:
```bash
npx skills add <sundny8>/visual-reverse-engineer -g -y
```
### 方式二:npm
```bash
# 直接运行,不安装
npx visual-reverse-engineer install --all
# 或全局安装后使用(带短别名 vre)
npm install -g visual-reverse-engineer
vre install --all
```
本包**自包含、无需联网**,内置技能文件直接复制到目标目录。
```bash
vre list # 查看内置技能与本机 agent
vre install -a claude-code,cursor,qoder
vre install -p --to ./my-project # 装到指定目录
vre uninstall --all
```
### 方式三:克隆仓库
```bash
git clone https://github.com/<sundny8>/visual-reverse-engineer.git
cd visual-reverse-engineer
# Node(零依赖)
node bin/cli.js install --all
# 或 Python 3.7+(零依赖,无需 Node)
python scripts/install.py --all
```
### 装到哪了
| Agent | 用户级(全局) | 项目级 |
| --- | --- | --- |
| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
| Codex CLI | `~/.codex/skills/` | `.agents/skills/` |
| Cursor | `~/.cursor/skills/` | `.agents/skills/` |
| Qoder | `~/.qoder/skills/` | `.qoder/skills/` |
| WorkBuddy | `~/.workbuddy-ai/skills/` | `.workbuddy-ai/skills/` |
| GitHub Copilot | `~/.copilot/skills/` | `.agents/skills/` |
| Gemini CLI | `~/.gemini/skills/` | `.agents/skills/` |
| Windsurf | `~/.codeium/windsurf/skills/` | `.windsurf/skills/` |
Windows 上 `~` 即 `C:\Users\<用户名>`。安装后**重启对应工具**才会加载新技能。
---
## 使用
装好后不用记命令,直接上传图片或视频说需求:
```
反推这张图的提示词
```
```
这张图是什么风格?
```
```
提取这张图的 JSON
```
```
照着这张图写提示词,尽量一模一样,只把背景换成雪山
```
```
分析这段视频的运镜和节奏,给出 Seedance 可用的提示词
```
```
只要提示词,不用分析
```
### 输出模式一览
| 技能 | 模式 | 输出区块 |
| --- | --- | --- |
| `image-reverse-analyst` | 固定三段 | ① 风格分析 ② 中文图片提示词 ③ 全英文 JSON |
| `visual-reverse-engineer` | 图片模式 | 视觉分析 / VISUAL DNA / 图片 Prompt / Negative Prompt |
| `visual-reverse-engineer` | 视频模式 | 上述 4 个 + 人物动作 / 环境运动 / 运镜 / 焦点变化 / 镜头节奏 / 时间轴 / 连续性锁定 |
| `visual-reverse-engineer` | 只要提示词 | 仅 Prompt + Negative Prompt |
| `visual-reverse-engineer` | 对比模式 | 逐图分析 + 对比表 + 融合 Prompt |
---
## 七条核心原则
以下七条由 `visual-reverse-engineer` 完整实现;`image-reverse-analyst` 实现了其中第 1、2、3 条(以 `OBSERVED` / `INFERRED` / `UNCERTAIN` 三级标注的形式)。
| # | 原则 | 落地方式 |
| --- | --- | --- |
| 1 | 反推而非描述 | Prompt 里写光位角度、焦段区间、景深范围,不写「很美」「有氛围感」 |
| 2 | 先分析后生成 | 强制先输出分析结构(VISUAL DNA / 风格分析),Prompt 从结构推导 |
| 3 | 事实与推测分离 | 每项标 `[observed]` / `[inferred]`,不可测参数必须标推测并附依据 |
| 4 | 最大化一致性 | 九级优先级:人物身份 ＞ 构图 ＞ 空间 ＞ 镜头 ＞ 光线 ＞ 材质 ＞ 色彩 ＞ 风格 ＞ 后期 |
| 5 | REFERENCE LOCK MODE | 十项锁定清单,只改用户指定项,并说明连带影响 |
| 6 | 视频连续性 | 逐项列出锁定清单 + 状态继承规则,禁止项写进 Negative |
| 7 | 动态 Negative | 扫描参考图实际风险元素逐项生成,**没有的元素不加** |
### 关于第 3 条(最重要的一条)
焦段、光圈、快门、ISO、灯位、灯型、后期软件——**这些物理上无法从单张画面确定**。
两个技能都强制把它们标为推测并附依据:
```
焦段 [inferred] 85–105mm — 依据:面部无透视形变,鼻与耳的距离被压缩
光圈 [inferred] f/4–f/5.6 — 依据:面部纵深内保持清晰,只有发梢开始虚
```
写进 Prompt 时用**约数或区间**:
```
Correct: shot on an 85mm lens, shallow depth of field around f/2
Wrong: shot on an 85mm f/1.4 lens at 1/250s ISO 400
```
前者诚实,用户拿它能复现;后者编造,用户按它调永远调不出那张图。
**并且两个技能都不会声称「这就是原始 Prompt」**——图像是多对一的,不同 Prompt 可以生成相似画面,任何反推都只能给出高概率重建。
---
## 仓库结构
```
visual-reverse-engineer/
├── package.json npm 包定义(bin: visual-reverse-engineer / vre)
├── bin/cli.js Node CLI 安装器(零依赖,通用版)
├── scripts/
│ ├── install.py Python 安装器(零依赖,Node 的替代方案)
│ └── validate.js 技能规范校验(CI 也跑这个)
├── skills/
│ ├── visual-reverse-engineer/
│ │ ├── SKILL.md 主入口:工作流 + 硬性约束 + 输出契约
│ │ ├── README.md
│ │ └── references/ 9 个参考文件,按需加载
│ └── image-reverse-analyst/
│ ├── SKILL.md 只做图片,固定三段式输出
│ ├── README.md
│ └── references/ 8 个参考文件,按需加载
└── .github/workflows/validate.yml
```
### 参考文件
**`visual-reverse-engineer`**
| 文件 | 内容 |
| --- | --- |
| `analysis-dimensions.md` | 23 个分析维度与识别方法 |
| `visual-dna.md` | VISUAL DNA 十分区 + 九级优先级 + 标注规范 |
| `image-mode.md` | 图片模式输出规范 |
| `video-mode.md` | 视频模式七个新增区块 |
| `reference-lock.md` | REFERENCE LOCK MODE 十项锁定 |
| `negative-prompt.md` | 动态负面词生成流程与分类词库 |
| `output-format.md` | 四种输出模式与排版规范 |
| `examples.md` | 图片 + 视频两个完整范例 |
| `full-prompt.md` | 单段式提示词(给只吃 system prompt 的工具) |
**`image-reverse-analyst`**
| 文件 | 内容 |
| --- | --- |
| `analysis-dimensions.md` | 十大维度(上):主体/构图/摄影/光影/色彩/材质 |
| `style-mood-symbolism.md` | 十大维度(下):风格/情绪/文字/象征 |
| `reverse-prompt.md` | 提示词重组 + 12 级优先级 + 空词替换表 |
| `json-schema.md` | JSON schema + 九条质量要求 + 常见错误 |
| `uncertainty-and-safety.md` | 三级可信度 + 安全替换对照表 |
| `output-format.md` | 三段式固定格式 |
| `examples.md` | 完整成品范例 |
| `full-prompt.md` | 单段式提示词(给只吃 system prompt 的工具) |
### 设计原则
**渐进式披露。** `SKILL.md` 只放工作流、硬性约束和输出契约;细节按主题拆进 `references/`,模型需要时才读。
**工具无关。** 不写任何单一 agent 的专有语法,脚本只用标准库。
**双安装器。** Node CLI 给 npm 用户,Python 脚本给没装 Node 的人,行为一致。
---
## 兼容性说明
Skills 遵循共享的 Agent Skills 规范(`SKILL.md` + YAML frontmatter 的 `name` / `description`),主流工具通用。
本仓库的技能**只依赖基础技能能力**,不绑定任何高级特性,因此在所有支持 Skills 的工具里行为一致。
### 不支持 Skills 的工具
网页版大模型、自定义 GPT 等没有 Skills 机制。这些场合用各技能下的 `references/full-prompt.md`:整段复制粘贴到 system prompt 或角色设定里,功能等价。
### 需要多模态输入
两个技能都依赖用户**上传图片**(视频反推还需视频输入)才能工作。如果你用的工具不支持图片输入,技能无法触发——这种情况下可以先用文字把画面描述给模型,但还原度会明显下降。
---
## 相关技能
本仓库的两个技能独立可用,不需要任何其他技能。如果你还需要**正向创作**能力(从零生成提示词),可以搭配:
| 技能 | 输入 | 用途 |
| --- | --- | --- |
| [`image-prompt-director`](https://github.com/<sundny8>/ai-visual-skills) | 一句话想法 | 正向创作:从零生成图片提示词 |
| [`seedance-director`](https://github.com/<sundny8>/ai-visual-skills) | 一句话想法 | 正向创作:从零生成 30 秒视频提示词 |
| **本仓库的两个技能** | 一张图 / 一段视频 | 逆向复现:从成品反推提示词 |
前两个是「无中生有」,本仓库是「照猫画虎」。
---
## 开发
```bash
npm test # 等价于 node scripts/validate.js
```
校验会检查 frontmatter 完整性、`name` 与目录名是否一致、`references/` 引用是否都存在、有没有混入 `_test` / `__pycache__` 之类的垃圾。
CI 在 push 与 PR 时自动跑 Node 18/20/22 三版本矩阵 + Python 冒烟测试。
### 发布到 npm
```bash
# 先把 package.json 里的 repository / homepage / bugs 改成你的仓库地址
npm login
npm publish --access public
```
`prepublishOnly` 钩子会在发布前自动跑校验,不通过就发布不了。
---
## License
[MIT](LICENSE)