image-asset-library

把本地任意类型的图片素材批量录入飞书多维表格（Feishu/Lark Bitable）的 Skill：自动八维打标 → 批量建记录 → 上传图片附件 → 数据质量校验。

A reusable Skill that batch-imports arbitrary local images into a Feishu/Lark Bitable with an 8-dimension tagging system, bulk record creation, attachment upload, and data-quality validation.

🇨🇳 中文 · 🇬🇧 English

中文文档

这是什么 / What is this

一个面向通用图片素材库维护的工作流 Skill。它能把一堆散落的图片（摄影、插画、图标、UI 截图、产品图、海报、表情包、头像、壁纸、数据图……）按统一的标签体系批量录入你指定的飞书多维表格，并长期维护。

与 ppt-inspiration-library（PPT 灵感库）的区别：本 Skill 不绑定 PPT 页面结构，维度更通用，且完全复用你已有的指定智能表格——通过字段映射把 8 个语义维度适配到你表格里的真实列名，不要求你照抄固定的表结构。

核心能力

八维标签体系：类别 / 风格 / 色系 / 主体 / 用途 / 氛围 / 信息密度 / 画面比例（每个维度有严格限定的可选值，禁止自造标签）。
批量工作流：扫描图片 → 逐张视觉分析打标 → 构造记录 JSON → 批量建记录 → 并行上传附件 → 维护已处理清单（断点续传）。
字段映射：通过 library_config.json 把语义维度映射到你的真实列名；表里没有对应列的维度自动跳过，也可补建。
数据校验：自检/线上校验双模式，检查空值、非法标签、缺失附件、重复记录。
断点续传：维护 processed_images.txt，文件名 NFC 标准化，避免中日韩编码差异导致重复处理。

目录结构

image-asset-library/
├── SKILL.md                          # 主指令（工作流、字段映射、命令速查）
├── README.md                         # 双语文档（中文 + English）
├── dimension-system.csv              # 八维体系导出表（语义key/字段名/类型/可选值），方便建表与对照
├── feishu_fields.json                # 飞书多维表格字段定义模板，可直接用于 +field-create 批量建字段
├── references/
│   ├── dimension-system.md           # 八维标签体系完整可选值（打标唯一依据）
│   ├── lark-workflow.md              # lark-cli base 子命令已验证参数 + 鉴权流程
│   └── library_config.example.json   # 配置文件模板
└── scripts/
    ├── scan_images.py                # 扫描/识别未处理图片，维护已处理清单
    ├── build_records.py              # 由 analysis.json + config 构造 create_records JSON（含标签强校验）
    ├── validate.py                   # 数据质量校验（空值/非法/附件/重复）
    └── upload_records.py             # 一键：建记录 + 上传附件（对单批 analysis.json）

依赖 / Dependencies

依赖	是否必需	说明
`lark-cli`	✅ 关键	飞书官方 CLI，用于读写多维表格与上传附件。本 Skill 针对 `v1.0.81` 验证；目标环境必须安装并完成 `auth login --domain base,drive` 授权。缺它则只能走到"打标 + 生成 JSON"，无法实际上传。
Python 3	✅	仅用标准库（`json/os/sys/argparse/unicodedata/subprocess`），无第三方包。
多模态读图能力	✅	第 3 步用 agent 的 Read 工具逐张视觉分析。agent 需支持图片理解。
一张飞书多维表格	✅	你自己的 Base（字段名可自定义，靠映射适配）。
`SKILL.md` 兼容的 agent	✅	本 Skill 为 WorkBuddy 的 `SKILL.md` 约定编写。

关于 lark-cli 鉴权：沙箱/CI 环境下 lark-cli config init 会卡在 macOS 钥匙串（被拦截）。已验证流程是先在本机跑 lark-cli config keychain-downgrade，再走 Device Flow 登录。详见 references/lark-workflow.md §0。

建表模板 / Table Templates

为方便别人直接建表，本仓库附带两份模板（与八维体系完全一致）：

dimension-system.csv：八维体系的扁平导出，列含 语义key / 飞书字段名 / 字段类型 / 可选值。可一眼对照，或导入 Excel/飞书做建表参考。
feishu_fields.json：飞书多维表格字段定义模板，字段顺序为 图片 → 类别 → 风格 → 色系 → 主体 → 用途 → 氛围 → 信息密度 → 比例 → 备注 → 文件名，单选/多选/附件/文本类型均已标注，多选字段预置全部可选值（保证标签严格受控）。

用 lark-cli 一键建好全部字段（遍历数组逐个 +field-create）：

# 在已建好的空 Base 中，循环创建字段
python3 - <<'PY'
import json, subprocess, sys
fields = json.load(open("feishu_fields.json", encoding="utf-8"))
BT, TID = "bascnXXXXXXXXXXXXXXXX", "tblXXXXXXXXXXXXXXXX"
for f in fields:
    cmd = ["lark-cli","base","+field-create","--base-token",BT,"--table-id",TID,
           "--json", json.dumps(f, ensure_ascii=False), "--as","user"]
    r = subprocess.run(cmd, capture_output=True, text=True)
    print(f["name"], "->", "OK" if r.returncode==0 else r.stderr.strip()[:120])
PY

字段名是默认建议名；你也可改用自定义列名，只要在 library_config.json 的 field_map 里把语义 key 映射到你的真实列名即可（见下文"快速开始"）。

快速开始 / Quick Start

1. 准备飞书表格与鉴权

# 安装 lark-cli 后，先在本机完成授权（沙箱环境需先 keychain-downgrade）
lark-cli auth login --domain base,drive
lark-cli auth status   # 应显示 user: ready, tokenStatus: valid

2. 写配置文件

复制 references/library_config.example.json 为 library_config.json，填入你的表格坐标与字段映射：

{
  "base_token": "bascnXXXXXXXXXXXXXXXX",
  "table_id": "tblXXXXXXXXXXXXXXXX",
  "attachment_field": "图片",
  "field_map": {
    "category": "类别", "style": "风格", "color": "色系",
    "subject": "主体", "usage": "用途", "mood": "氛围",
    "density": "信息密度", "ratio": "比例", "desc": "备注", "filename": "文件名"
  }
}

也支持给分享链接让 Skill 用 +url-resolve 解析坐标；或直接把配置放图片文件夹，Skill 检测到即读取。

3. 跑完整流程（交给 agent 执行 Skill 即可）

agent 加载 Skill 后会按 SKILL.md 的工作流逐步执行：

图片文件夹 → 确认坐标+字段映射 → 扫描未处理图片
→ 逐张视觉分析打 8 维标签 → 写 analysis.json
→ build_records.py 构造 create_records → 批量建记录
→ 并行上传图片附件 → 更新已处理清单

你也可以手动分步调用脚本：

# ① 列出未处理图片
python3 scripts/scan_images.py --image-dir /path/to/images --list

# ②（agent 完成打标后）构造记录 JSON，并强校验标签
python3 scripts/build_records.py --analysis analysis.json --config library_config.json --out batch.json

# ③ 批量建记录 + 上传附件（依赖 lark-cli）
python3 scripts/upload_records.py --image-dir /path/to/images --analysis analysis.json --config library_config.json

# ④ 校验数据质量
python3 scripts/validate.py --analysis analysis.json

八维标签体系（概览）

完整可选值见 references/dimension-system.md（打标唯一依据，禁止自造）。

维度 key	类型	示例可选值
`category` 类别	单选	插画 / 摄影照片 / 图标 / UI截图 / 产品图 / 海报 / 表情包·贴纸 / 头像 / 壁纸 / 数据可视化 / 3D渲染 / 手绘 / 矢量图 / 其他
`style` 风格	多选	写实 / 扁平 / 极简 / 国潮 / 科技感 / 复古 / 手绘 / 卡通风 / 3D / 水彩 / 像素风 / 渐变 / 孟菲斯 / 杂志风 / 暗黑 / 小清新 / 拟物 / 霓虹
`color` 色系	多选	红 / 橙 / 黄 / 绿 / 蓝 / 紫 / 黑白灰 / 莫兰迪 / 多彩 / 暖色系 / 冷色系 / 撞色 / 金色系 / 粉色系
`subject` 主体	多选	人物 / 动物 / 植物 / 食物 / 建筑 / 风景·自然 / 科技·数码 / 文字排版 / 几何图形 / 图标 / 抽象 / 车辆 / 商品 / 手势
`usage` 用途	多选	公众号配图 / 海报背景 / PPT配图 / 社媒封面 / 头像 / 表情包 / 电商主图 / 壁纸 / 网页Banner / 配图素材 / 演示背景 / 视频封面
`mood` 氛围	多选	活泼 / 温暖 / 专业 / 高级 / 清冷 / 喜庆 / 治愈 / 神秘 / 科技 / 幽默 / 严肃 / 浪漫 / 未来感
`density` 信息密度	单选	高 / 中 / 低
`ratio` 画面比例	单选	横图(16:9) / 竖图(9:16) / 方图(1:1) / 全景 / 其他

另含文本字段：desc 备注（中文详细描述）、filename 文件名（去重/溯源）。

脚本说明

脚本	作用	关键参数
`scan_images.py`	递归扫描图片、识别未处理项、维护 `processed_images.txt`	`--image-dir --list / --mark-done`
`build_records.py`	按 `field_map` 映射语义 key → 真实列名，强制校验标签合法性，输出 `create_records` JSON（不含附件）	`--analysis --config --out`
`validate.py`	数据质量校验：完整性 / 合法性 / 附件完整性 / 重复记录	`--analysis` 或 `--records --config`
`upload_records.py`	对单批 `analysis.json`：建记录 + 逐条上传附件（依赖 `lark-cli`）	`--image-dir --analysis --config`

复用 / 移植到其他 Agent（重要）

本 Skill 设计为文件自包含，但能否真正跑通取决于目标环境：

格式兼容：本 Skill 遵循 WorkBuddy SKILL.md 约定（frontmatter + 渐进式指令）。直接复制到另一个 WorkBuddy / 兼容该格式的 agent 的 skills 目录即可被识别。若目标是 Claude Code / Cursor / Codex 等使用不同格式（commands / AGENTS.md / .cursorrules）的 agent，需改写适配。
lark-cli 是硬依赖：步骤 5/6（建记录、传附件）完全依赖 lark-cli base。目标环境必须安装（版本接近 v1.0.81）并完成飞书授权，否则上传链路不可用。
多模态读图：第 3 步依赖 agent 的视觉理解能力，否则需改为人工填标或接入其他视觉模型。
后端绑定：上传链路写死在 Feishu/Lark Bitable。换 Notion / Airtable / 本地库需重写 lark-workflow.md 与 upload_records.py 中的 CLI 调用。
Python 脚本零依赖：4 个脚本仅用标准库，可移植性极好，可独立复用到任意 Python3 环境。

一句话：目标也是 WorkBuddy、能装并授权 lark-cli、且能读图 → 复制文件夹即开用；否则按上述清单补齐依赖或做适配改写。

常见问题

现象	原因	修复
`permission denied / token expired`	认证过期	`lark-cli auth login --domain base` 重新授权
`unsafe file path`	附件用了绝对路径	先 `cd` 进图片目录，用相对路径 `--file`
`invalid JSON`	中文引号/尾随逗号	用文件传参，检查引号
标签被拒	用了可选值外的值	查 `dimension-system.md`，改回合法值后重跑 `build_records.py`
`--limit` 超限	分页超限	最大 200，循环 `offset` 翻页

License

MIT —— 自由用于个人与商业项目，欢迎提 PR 完善标签体系与后端适配。

English

What is this

A workflow Skill for maintaining a general-purpose image asset library. It batches a pile of scattered images into your specified Feishu Bitable with a unified tagging system, and keeps the library maintained over time.

Unlike the ppt-inspiration-library Skill, this one is not tied to a PPT page structure; the dimensions are more general, and it fully reuses your existing Bitable — mapping 8 semantic dimensions to your real column names via a field map, so you don't have to copy a fixed table schema.

Features

8-dimension taxonomy: category / style / color / subject / usage / mood / density / ratio (each with strictly allowed values — no free-form tags).
Batch workflow: scan images → analyze & tag each image → build records JSON → batch-create records → parallel attachment upload → maintain processed list (resumable).
Field mapping: map semantic keys to your real column names via library_config.json; dimensions without a matching column are skipped (or auto-created).
Data validation: local and online modes check for empty values, illegal tags, missing attachments, and duplicate records.
Resumable: maintains processed_images.txt, with NFC-normalized filenames to avoid dupes caused by CJK encoding differences.

Repository structure

image-asset-library/
├── SKILL.md                          # Main instructions (workflow, field mapping, command cheat-sheet)
├── README.md                         # Bilingual documentation (中文 + English)
├── LICENSE                           # MIT
├── .gitignore
├── dimension-system.csv              # 8-dimension taxonomy export (semantic key / field name / type / allowed values)
├── feishu_fields.json                # Feishu Bitable field definitions (ready for +field-create)
├── references/
│   ├── dimension-system.md           # Full allowed values for the 8 dimensions (the only source of truth for tagging)
│   ├── lark-workflow.md              # Verified lark-cli base subcommands + auth flow
│   └── library_config.example.json   # Config template
└── scripts/
    ├── scan_images.py                # Scan/identify unprocessed images, maintain processed list
    ├── build_records.py              # Build create_records JSON from analysis.json + config (with strict tag validation)
    ├── validate.py                   # Data-quality validation (empties / illegal / attachments / duplicates)
    └── upload_records.py             # One-shot: create records + upload attachments for one batch

Dependencies

Dependency	Required	Notes
`lark-cli`	✅ critical	Feishu CLI for Bitable read/write and attachment upload. Tested on `v1.0.81`. The target environment must install it and run `auth login --domain base,drive`. Without it you can only reach "tagging + JSON generation" — upload is impossible.
Python 3	✅	Standard library only (`json/os/sys/argparse/unicodedata/subprocess`), no third-party packages.
Multimodal image reading	✅	Step 3 uses the agent's Read tool to analyze each image; the agent needs vision.
A Feishu Bitable	✅	Your own Base (column names customizable via mapping).
A `SKILL.md`-compatible agent	✅	Written for the WorkBuddy `SKILL.md` convention.

lark-cli auth in sandbox/CI: lark-cli config init can hang on the macOS keychain. The verified flow is lark-cli config keychain-downgrade on the host first, then Device-Flow login. See references/lark-workflow.md §0.

Quick start

1. Prepare the Bitable and authenticate

lark-cli auth login --domain base,drive
lark-cli auth status   # should show: user: ready, tokenStatus: valid

2. Write the config

Copy references/library_config.example.json to library_config.json, fill in your table coordinates and field mapping:

{
  "base_token": "bascnXXXXXXXXXXXXXXXX",
  "table_id": "tblXXXXXXXXXXXXXXXX",
  "attachment_field": "图片",
  "field_map": {
    "category": "类别", "style": "风格", "color": "色系",
    "subject": "主体", "usage": "用途", "mood": "氛围",
    "density": "信息密度", "ratio": "比例", "desc": "备注", "filename": "文件名"
  }
}

3. Run the workflow (or hand it to the agent)

# ① list unprocessed images
python3 scripts/scan_images.py --image-dir /path/to/images --list

# ② (after tagging) build records JSON, with strict tag validation
python3 scripts/build_records.py --analysis analysis.json --config library_config.json --out batch.json

# ③ create records + upload attachments (requires lark-cli)
python3 scripts/upload_records.py --image-dir /path/to/images --analysis analysis.json --config library_config.json

# ④ validate data quality
python3 scripts/validate.py --analysis analysis.json

8-dimension taxonomy (overview)

Full allowed values are in references/dimension-system.md — the only source of truth for tagging; do not invent values.

Dimension key	Type	Example allowed values
`category`	single	插画 / 摄影照片 / 图标 / UI截图 / 产品图 / 海报 / 表情包·贴纸 / 头像 / 壁纸 / 数据可视化 / 3D渲染 / 手绘 / 矢量图 / 其他
`style`	multi	写实 / 扁平 / 极简 / 国潮 / 科技感 / 复古 / 手绘 / 卡通风 / 3D / 水彩 / 像素风 / 渐变 / 孟菲斯 / 杂志风 / 暗黑 / 小清新 / 拟物 / 霓虹
`color`	multi	红 / 橙 / 黄 / 绿 / 蓝 / 紫 / 黑白灰 / 莫兰迪 / 多彩 / 暖色系 / 冷色系 / 撞色 / 金色系 / 粉色系
`subject`	multi	人物 / 动物 / 植物 / 食物 / 建筑 / 风景·自然 / 科技·数码 / 文字排版 / 几何图形 / 图标 / 抽象 / 车辆 / 商品 / 手势
`usage`	multi	公众号配图 / 海报背景 / PPT配图 / 社媒封面 / 头像 / 表情包 / 电商主图 / 壁纸 / 网页Banner / 配图素材 / 演示背景 / 视频封面
`mood`	multi	活泼 / 温暖 / 专业 / 高级 / 清冷 / 喜庆 / 治愈 / 神秘 / 科技 / 幽默 / 严肃 / 浪漫 / 未来感
`density`	single	高 / 中 / 低
`ratio`	single	横图(16:9) / 竖图(9:16) / 方图(1:1) / 全景 / 其他

Plus text fields: desc (Chinese description) and filename (for dedup/traceability).

Table templates

This repo ships two templates that match the 8-dimension system exactly:

dimension-system.csv — flat export of the taxonomy (semantic key / Feishu field name / field type / allowed values). Use it as a reference when building the table in Excel/Feishu.
feishu_fields.json — Feishu Bitable field definitions (order: 图片 → 类别 → 风格 → 色系 → 主体 → 用途 → 氛围 → 信息密度 → 比例 → 备注 → 文件名), with single/multi/attachment/text types and all allowed values pre-seeded for multi-select fields (keeps tags strictly controlled).

Create all fields at once (loop over the array):

python3 - <<'PY'
import json, subprocess
fields = json.load(open("feishu_fields.json", encoding="utf-8"))
BT, TID = "bascnXXXXXXXXXXXXXXXX", "tblXXXXXXXXXXXXXXXX"
for f in fields:
    cmd = ["lark-cli","base","+field-create","--base-token",BT,"--table-id",TID,
           "--json", json.dumps(f, ensure_ascii=False), "--as","user"]
    r = subprocess.run(cmd, capture_output=True, text=True)
    print(f["name"], "->", "OK" if r.returncode==0 else r.stderr.strip()[:120])
PY

Field names are default suggestions; you may rename columns and map them back via field_map in library_config.json.

Reusing / porting to other agents

This Skill is self-contained as files, but whether it actually runs depends on the target environment:

Format compatibility: follows the WorkBuddy SKILL.md convention. Copy it into another WorkBuddy (or compatible) agent's skills directory and it will be recognized. For Claude Code / Cursor / Codex (which use commands / AGENTS.md / .cursorrules), it needs rewriting.
lark-cli is a hard dependency: steps 5/6 (create records, upload attachments) rely entirely on lark-cli base. The target must install (version ≈ v1.0.81) and authorize it with Feishu, otherwise the upload chain is unavailable.
Multimodal image reading: step 3 depends on the agent's vision capability, otherwise you must tag manually or plug in another vision model.
Backend is pinned to Feishu Bitable: switching to Notion / Airtable / a local DB requires rewriting lark-workflow.md and upload_records.py.
Python scripts are zero-dependency: the four scripts use only the standard library and are highly portable — reusable in any Python 3 environment.

In one sentence: if the target is also WorkBuddy, can install and authorize lark-cli, and can read images → copy the folder and it works; otherwise fill the gaps above or adapt.

FAQ

Symptom	Cause	Fix
`permission denied / token expired`	auth expired	`lark-cli auth login --domain base`
`unsafe file path`	absolute path for attachment	`cd` into the image dir, use relative `--file`
`invalid JSON`	Chinese quotes / trailing comma	pass via file, check quotes
tags rejected	value outside allowed set	check `dimension-system.md`, fix and re-run `build_records.py`
`--limit` exceeded	paging limit	max 200, loop `offset`

License

MIT — free for personal and commercial use. PRs to improve the taxonomy or add backends are welcome.

Navigation Menu

Repository files navigation

image-asset-library

中文文档

这是什么 / What is this

核心能力

目录结构

依赖 / Dependencies

建表模板 / Table Templates

快速开始 / Quick Start

1. 准备飞书表格与鉴权

2. 写配置文件

3. 跑完整流程（交给 agent 执行 Skill 即可）

八维标签体系（概览）

脚本说明

复用 / 移植到其他 Agent（重要）

常见问题

相关仓库 / Related

License

English

What is this

Features

Repository structure

Dependencies

Quick start

1. Prepare the Bitable and authenticate

2. Write the config

3. Run the workflow (or hand it to the agent)

8-dimension taxonomy (overview)

Table templates

Reusing / porting to other agents

FAQ

Related

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
references		references
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
dimension-system.csv		dimension-system.csv
feishu_fields.json		feishu_fields.json

Latest commit

History

Folders and files

Repository files navigation

image-asset-library

中文文档

这是什么 / What is this

核心能力

目录结构

依赖 / Dependencies

建表模板 / Table Templates

快速开始 / Quick Start

1. 准备飞书表格与鉴权

2. 写配置文件

3. 跑完整流程（交给 agent 执行 Skill 即可）

八维标签体系（概览）

脚本说明

复用 / 移植到其他 Agent（重要）

常见问题

相关仓库 / Related

License

English

What is this

Features

Repository structure

Dependencies

Quick start

1. Prepare the Bitable and authenticate

2. Write the config

3. Run the workflow (or hand it to the agent)

8-dimension taxonomy (overview)

Table templates

Reusing / porting to other agents

FAQ

Related

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages