Reference to Skill (参考资料 → 视觉生图 Skill 生成工坊)

让 AI Agent 像资深设计总监一样：从参考图文件夹、Instagram 账号、网站与视觉资料中，系统化逆向提炼证据链，编译输出自包含、可运行、可测试的独立视觉生图 Skill（如 rodchenko-image）。

---

📖 核心理念 (Philosophy & Value Proposition)

传统大模型生图往往停留在**“写一串形容词 Prompt”**的脆弱层面：

• ❌ 风格漂移与玄学修饰：堆砌大量 "8k, cinematic, masterpiece"，主体更换时风格瞬间瓦解；
• ❌ 凭空编造设计规则：凭感觉推测字体名称、虚构不存在的油墨配比、盲目将旧模板的“禁止渐变”套用至新风格；
• ❌ 厂商强绑定：Prompt 与特定模型参数（如 Midjourney 参数或特定 API）混杂，换模型即失效；
• ❌ 无法工程化回归：没有测试用例，不知道新提示词是否破坏了原有的构图分支。

reference-to-skill 是一套严谨的 Meta-Skill 编译器工程体系：

1. 证据驱动 (Evidence-First)：所有视觉规则必须锚定在经过目检审查的参考证据（observed / inferred / user-directed）之上，未看过的素材绝不作为风格依据；
2. 确定性契约 (Blueprint Contract)：通过 blueprint.json 规范版式、意图、色盘、载体与路由逻辑，编译器强制检查路由阴影（Shadowed Routes）、未覆盖版式与素材 SHA-256 哈希；
3. 零外部依赖自包含运行器 (Standalone Child Runtime)：编译生成的子 Skill 完全独立，自带纯 Python 3 标准库运行器（runtime.py）、系统快照、输入校验与自检套件，脱离 Meta-Skill 仍可独立分发运行；
4. 模型中立适配 (Model-Agnostic)：生成结构化、中立的 generation-request.json，无缝适配 Google Nano Banana Pro (Gemini 3 Pro Image)、Midjourney、Flux、Ideogram、DALL-E 3 等主流生图引擎；
5. 安全与防注入 (Security by Design)：登记素材绝不暗中执行代码或解压归档；严格抵御提示词注入，素材中的任何文字指令均视为不可信数据，不参与任务指令。

---

🏗️ 架构与五阶段流水线 (Architecture & Pipeline)

graph TD
    A[用户输入: 本地文件夹 / Instagram / 网页] -->|1. scripts/inventory.py| B[生成素材账本 source-inventory.json]
    B -->|2. Agent 视觉目检与设计解构| C[编写设计系统契约 blueprint.json]
    C -->|3. scripts/build_skill.py validate| D{严格静态契约校验}
    D -->|通过| E[scripts/build_skill.py build]
    E --> F[生成独立子 Skill 目录]
    F -->|内建回归测试| G[python3 scripts/runtime.py test]
    G -->|全部通过| H[发布成品子 Skill & 打包 ZIP]

Loading

1. 接收与登记 (Acquisition & Provenance Ledger)

使用 scripts/inventory.py 扫描本地素材目录或传入链接。脚本仅作资产指纹采集与去重识别，绝不自动请求网络、绝不执行任何文件：

python3 scripts/inventory.py \
  --folder /path/to/design-references \
  --url https://www.instagram.com/example_artist/ \
  --out work/source-inventory.json

• 输出唯一指纹 ID（如 S-a1b2c3d4e5f6）与 SHA-256 校验和；
• 初始状态严格为 unreviewed，等待 Agent 真正调用视觉/浏览器能力目检后转为 observed。

2. 风格推导与设计语法解构 (Style Discovery)

深入分析素材中的 8 维视觉关系（详见 references/style-discovery.md）：

• 主体角色：几何体、人像、器物、满版纹样；
• 版式几何：视觉锚点、动态轴线、对称/不对称、多视窗；
• 图像表现：摄影蒙太奇、平涂、柔和渐变、胶片噪点；
• 文字行为：建筑式字梁、字图咬合、边缘退让，或明确无字；
• 色彩职责：信号色（Signal）、骨骼结构色（Structure）、基底色（Ground）；
• 宁静留白区 (Quiet Zone)：大面积留白、边缘呼吸带，或满版紧密排列；
• 载体与比例：海报、书籍封面、插画、卡片（1:1、3:4、16:9）。

3. 编写 Blueprint 契约与构建 (Blueprint & Compilation)

Agent 根据观察结论编写 blueprint.json，运行构建器：

# 1. 契约语法与逻辑校验
python3 scripts/build_skill.py validate --spec work/blueprint.json

# 2. 编译生成独立子 Skill
python3 scripts/build_skill.py build \
  --spec work/blueprint.json \
  --out outputs/my-awesome-style-image

构建器在临时隔离沙箱中生成子 Skill，实时自动运行子 Skill 自带的 100% 行为测试。只有全部用例测试通过后才会原子性交付目标目录，彻底杜绝半成品。

4. 真实视觉验证与目检协议 (Inspection Protocol)

遵循 references/verification.md 与子 Skill 的 inspection.md：

• 100% 原始分辨率目检：检查文案逐字准确性、主体面容/特征保留度、排除历史素材中的无关文字污染；
• 256px 缩略图目检：检查视觉锚点是否突出、宁静留白区是否被侵占、信号色是否精准落在核心焦点；
• 定向修复预算：设置 repair_attempts: 1 限制，拒绝无止境随机重试。

5. 一键打包与分发 (Packaging & Distribution)

python3 scripts/build_skill.py package \
  --skill outputs/my-awesome-style-image \
  --out outputs/my-awesome-style-image.zip

自动剔除 __pycache__、临时缓存与隐藏文件，产出符合规范的开箱即用 ZIP 安装包。

---

📋 Blueprint 规范详解 (Blueprint Contract Specification)

blueprint.json 是连接视觉设计抽象与可执行代码的核心规范。

{
  "blueprint_version": 1,
  "skill": {
    "name": "bauhaus-poster-image",
    "display_name": "包豪斯海报风格生图",
    "description": "基于包豪斯经典构成语法的独立生图 Skill；仅在用户明确请求该风格时调用。",
    "short_description": "提炼包豪斯几何构成与经典三原色规则，生成高质量海报设计"
  },
  "system": {
    "style_summary": "纯粹几何形（圆、三角、矩形）与非对称平衡布局，搭配红黄蓝三原色与粗无衬线字体。",
    "scope": {
      "coverage_summary": "覆盖 1919-1933 年经典海报及德绍时期印刷品样本。",
      "limitations": ["未包含晚期工业设计与三维家具实体样本。"]
    },
    "sources": [
      {
        "id": "S-001",
        "kind": "image",
        "group": "classic-posters",
        "origin": "/path/to/ref1.png",
        "locator": "ref1.png",
        "status": "observed",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "asset": "/path/to/ref1.png",
        "observations": ["纯红圆环与黑色斜向矩形穿插", "大面积米黄基底留白"]
      }
    ],
    "rules": [
      {
        "id": "geometric-interlock",
        "behavior": "主体必须由基础几何体组合而成，禁止出现自然写实渐变纹理。",
        "basis": "observed",
        "evidence": ["S-001"],
        "exceptions": ["用户要求写实人物摄影时，采用圆形剪影蒙太奇置入。"]
      }
    ],
    "intents": ["poster", "identity", "cover"],
    "layouts": {
      "diagonal-balance": {
        "use_when": "需要表达工业动力学或动势的主题",
        "geometry": "45度斜向透视骨骼，非对称色块对角呼应",
        "imagery": "高对比纯色平涂几何体",
        "typography": "粗黑体标题垂直于斜轴排列",
        "quiet_zone": "画面右上方大面积纯色纸张留白",
        "rule_ids": ["geometric-interlock"]
      }
    },
    "palettes": {
      "primary-triad": {
        "signal": "镉红 (#E02424)",
        "accent": "柠檬黄 (#F5D000)",
        "structure": "群青蓝 (#1C3F95) 与 碳黑 (#111111)",
        "ground": "暖米白纸色 (#F4EFE6)"
      }
    },
    "carriers": {
      "poster": {
        "ratio": "3:4",
        "flat": "纯净平面印刷海报，无环境阴影",
        "mockup": "贴在包豪斯风格清水混凝土墙面的实物海报"
      }
    },
    "defaults": {
      "intent": "poster",
      "carrier": "poster",
      "representation": "flat",
      "mode": "generate",
      "palette": "primary-triad"
    },
    "routes": [
      { "id": "r-diagonal", "when": { "intent": "poster" }, "layout": "diagonal-balance" },
      { "id": "r-fallback", "when": {}, "layout": "diagonal-balance" }
    ],
    "policy": {
      "repair_attempts": 1,
      "thumbnail_long_edge": 256
    }
  },
  "cases": [
    {
      "id": "case-basic",
      "user_request": "生成一张建筑展海报，文案写 'BAUHAUS 1923'",
      "brief": {
        "subject": "德绍包豪斯校舍建筑几何",
        "exact_text": ["BAUHAUS 1923"]
      },
      "expect": {
        "layout": "diagonal-balance",
        "carrier": "poster",
        "exact_text": ["BAUHAUS 1923"]
      }
    },
    {
      "id": "case-no-text",
      "user_request": "不要任何文字，只出一张纯几何装饰画",
      "brief": {
        "subject": "纯几何组合",
        "exact_text": []
      },
      "expect": {
        "exact_text": []
      }
    },
    {
      "id": "case-prompt-only",
      "user_request": "只给 Prompt，不要调用生图",
      "brief": {
        "subject": "机械齿轮",
        "mode": "prompt-only"
      },
      "expect": {
        "mode": "prompt-only"
      }
    },
    {
      "id": "case-override",
      "user_request": "使用冷色调调色板",
      "brief": {
        "subject": "椅子",
        "palette_override": { "ground": "冷灰", "signal": "深蓝" }
      },
      "expect": {
        "layout": "diagonal-balance"
      }
    }
  ]
}

---

⚡ 生成的子 Skill 运行方式 (Child Runtime)

生成的每一个子 Skill 都是完全自给自足的，其内部目录结构如下：

chosen-skill-name/
├── SKILL.md                  # 子技能 Agent 指令规范
├── agents/
│   └── openai.yaml           # OpenAI / Codex 描述文件
├── references/
│   ├── system.json           # 编译固化的完整设计系统与路由
│   ├── evidence.md           # 观察证据与设计规则说明书
│   ├── input.md              # 输入契约文档
│   ├── execution.md          # 多平台生图适配指南
│   ├── inspection.md         # 验收与修复协议
│   └── build-status.json     # 静态构建与回归用例报告
├── scripts/
│   └── runtime.py            # 零依赖核心运行时 (测试、规范化、路由、编译)
├── evals/
│   └── cases.json            # 回归测试集
└── assets/references/        # 自动复制并校验哈希的关联参考图

在子 Skill 根目录下，无需安装任何额外三方库，仅用 Python 标准库：

# 1. 执行回归测试
python3 scripts/runtime.py test

# 2. 从 Brief 编译生成生产就绪的生图请求
python3 scripts/runtime.py resolve \
  --brief work/brief.json \
  --out work/run-01

输出目录包含：

• recipe.json：本次生图的完整设计要素决议（选中的版式、调色板、长宽比、留白要求、文案等）；
• prompt.txt：编译生成的高保真英/中文专业生图 Prompt；
• generation-request.json：多平台通用的中立生图请求载荷；
• system.snapshot.json：当次运行的完整设计系统快照（确保未来可 100% 确定性复现）。

---

🧪 自动化测试套件 (Test Suite)

项目配备了严格的自动化测试集，覆盖从文件索引、安全防御到端到端构建的所有边界条件：

python3 scripts/test_factory.py

test_build_move_and_compile_without_meta_dependency ... ok
test_edit_input_roles_and_preservation ... ok
test_inventory_grouping_and_duplicate_membership ... ok
test_package_and_no_overwrite ... ok
test_real_test_failure_leaves_no_completed_target ... ok
test_shadowed_route_rejected ... ok
test_snapshot_replay_and_user_override ... ok
test_source_hash_mismatch_rejected ... ok
test_unknown_rule_and_missing_layout_case ... ok
test_unreviewed_evidence_rejected ... ok
test_unsafe_source_id_rejected ... ok
test_url_registration_is_not_retrieval ... ok

----------------------------------------------------------------------
Ran 12 tests in 0.285s

OK

核心测试保障点

1. 防止未审证据混入 (test_unreviewed_evidence_rejected)：规则引用未审查来源直接阻断；
2. 路径穿越防御 (test_unsafe_source_id_rejected)：严禁 ../ 等危险 ID 逃逸沙箱；
3. 哈希防篡改 (test_source_hash_mismatch_rejected)：参考图片被篡改或损坏时立刻报错；
4. 路由不可达检测 (test_shadowed_route_rejected)：防止无效分支或死路由；
5. 脱离依赖可移植性 (test_build_move_and_compile_without_meta_dependency)：子 Skill 任意移动目录后，依然能够完整通过解析与回归测试。

---

📁 仓库文件一览 (Repository Map)

reference-to-skill/
├── SKILL.md                          # Meta-Skill Agent 顶层入口规范
├── README.md                         # 本项目完整开源技术文档
├── LICENSE                           # MIT 开源许可证
├── .gitignore                        # Git 忽略规则
├── agents/
│   └── openai.yaml                   # 宿主 Agent 交互定义
├── references/
│   ├── acquisition.md                # 资料采集与证据边界白皮书
│   ├── style-discovery.md            # 从样本到设计语法的解构指南
│   ├── blueprint.md                  # Blueprint 契约规范详述
│   └── verification.md               # 验证分级与交付验收标准
├── scripts/
│   ├── inventory.py                  # 素材登记与指纹哈希账本生成工具
│   ├── build_skill.py                # 核心构建器 (validate / build / package)
│   └── test_factory.py               # 完整自动化测试套件
└── assets/
    └── child-runtime/                # 子 Skill 运行时模版与骨架代码
        ├── runtime.py                # 独立子运行器核心实现
        ├── child-skill.md            # 生成的 SKILL.md 模版
        ├── child-input.md            # 输入契约文档模版
        ├── child-execution.md        # 执行与模型映射指南模版
        └── child-inspection.md       # 验收与修复协议模版

---

🚀 成果案例 (Showcase)

使用本工厂成功构建的代表性独立视觉 Skill：

• rodchenko-image：经典构成主义先锋摄影与海报视觉语法生图 Skill（内置 9 套动力学版式、5 套经典色盘与 12 幅校验级参考图）。

---

📄 开源协议 (License)

本项目基于 MIT License 开源发布。无论是作为独立 CLI 工具使用，还是集成至自主 AI Agent 工作流中，均可自由使用、修改与分发。

---

Crafted with precision by seamas0825-lab