Agent/knowhub/scripts/rename_merged_capabilities.py

#!/usr/bin/env python3
"""
对合并后的 canonical capability 更新 name + description，
使其覆盖所有被合并成员的语义范围。

不动 embedding / criterion / effects（按约定）。

用法：
  python knowhub/scripts/rename_merged_capabilities.py --dry-run
  python knowhub/scripts/rename_merged_capabilities.py --execute
"""
import argparse
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent.parent.parent))
from knowhub.knowhub_db.pg_capability_store import PostgreSQLCapabilityStore


# canonical_id -> (new_name, new_description)
# 只列需要改的（26 条）；其余保持原状
RENAMES = {
    # [1] 抠图：原 desc 只提"食材/产品"，泛化为通用主体 + 毛发边缘
    "CAP-12d2aa10": (
        "AI 智能主体抠图与背景分离",
        "利用 AI 语义分割模型自动识别图像中的主体（人物、动物、食材、产品、物体等），"
        "精准将其从原始背景中分离，输出带透明通道（Alpha）的 PNG。支持毛发、发丝等复杂边缘的精细处理，"
        "无需手动绘制蒙版或逐像素操作，供后续叠加合成、背景替换或拼贴使用。"
    ),
    # [3] 含"切割"和"无缝拼接/轮播切分"两条路径
    "CAP-fddd3349": (
        "网格/全景大图自动切割为独立子图",
        "将包含多个画面单元的网格大图（3×3 九宫格、4×4 十六格等）或宽幅全景图，"
        "按网格坐标或等宽比例自动切割为多张尺寸一致、边缘整齐的子图，"
        "可按顺序单独发布到社交媒体（Instagram 轮播、无缝横幅等）或用于后续处理，无需二次裁剪。"
    ),
    # [7] 扩展到色彩偏移 + 色调风格（8ce1a9c6 / c9b3c7a5）
    "CAP-6c14041c": (
        "胶片与镜头光学质感模拟（柔焦/散景/颗粒/暗角/色调/光晕）",
        "通过在提示词中注入胶片摄影的光学特征与色调关键词（柔焦、散景、胶片颗粒、暗角、辉光/Halation、"
        "Kodak Portra 400 暖调、复古胶片颗粒、镜头光晕 Lens Flare、镜头绽放 Lens Bloom），"
        "模拟真实胶片相机的光学成像与色调特性，使生成图像呈现朦胧、疏离、梦幻的胶片质感氛围。"
    ),
    # [8] 扩展到相机位置（高度/倾斜/旋转/视野）
    "CAP-ef0a4c0c": (
        "摄影级镜头与相机参数模拟",
        "在 AI 图像生成提示词中嵌入专业摄影参数（焦距 mm、光圈 f/值、ISO、快门速度、色温 K 值、画幅格式、"
        "传感器尺寸、白平衡）以及相机位置与姿态（高度、倾斜、旋转、视野范围），"
        "使生成图像模拟特定摄影设备和拍摄参数下的真实光学效果（景深虚化、色温偏移、镜头畸变），"
        "并在多次生成中保持相机参数一致。"
    ),
    # [9] 扩展光源方向控制
    "CAP-1649b549": (
        "戏剧性明暗对比与光源方向控制（Chiaroscuro / Low-Key）",
        "通过提示词精准控制画面的明暗分布比例与光源方向（侧光、逆光、硬光、背光），"
        "实现暗部极深（接近纯黑）、亮部极亮（接近纯白）的戏剧性反差，"
        "模拟卡拉瓦乔式明暗对照法（Chiaroscuro/Tenebrism）、低调光（Low-Key）或暗调长调配色的视觉风格，"
        "赋予画面强烈情绪张力和电影感。"
    ),
    # [11] 扩展到服装+配饰+保持外观
    "CAP-d92ffc99": (
        "AI 虚拟换装与服装配饰迁移",
        "以参考服装/配饰图像为输入，将指定单品（服装、帽子、眼镜、假发、项链等）自动迁移并穿戴到目标人物或角色上，"
        "保持服装款式/颜色/纹理/图案细节不变，同时与主体体型、姿态和场景光照自然融合。"
        "支持平铺图到模特上身转换、保持角色面部外观不变的跨造型换装，适用于电商展示、虚拟试衣。"
    ),
    # [13] 加主体库复用
    "CAP-5342ad19": (
        "角色设定卡 / 多视图参考表生成",
        "基于文字描述或单张参考图，一次性生成同一角色的多角度视图（正面/侧面/背面全身）、"
        "多表情特写以及服装/配饰细节，形成标准化的角色参考表（Character Sheet）或多视图主体库，"
        "作为后续跨场景、跨工具的角色一致性生成的视觉锚点，支持复用。"
    ),
    # [14] 泛化到 ControlNet / 单图多视角
    "CAP-ee7df476": (
        "参数化/ControlNet 驱动的多视角图像生成",
        "以单张参考图为输入，通过参数化控制（方位角 Azimuth、仰角 Elevation、距离 Distance）"
        "或 LoRA 坐标系、ControlNet、深度估计等技术，精确控制视角旋转，"
        "生成同一主体在 360° 任意水平/垂直方向上的视角变体，不依赖提示词抽卡。"
    ),
    # [16] 扩展到人像景观融合
    "CAP-19e5402a": (
        "双重曝光剪影叙事构图生成",
        "以人物或物体的剪影轮廓为外框/容器，在轮廓内部填充与主题绑定的完整世界观场景"
        "（宇宙星云、山地景观、粒子场、自然景致、微型世界），"
        "结合空气透视、水彩刷痕、边缘飞白、雾气/粒子/光晕自然过渡等视觉语言，"
        "生成具有电影海报质感的双重曝光叙事插画，人像与景观相互渗透。"
    ),
    # [19] 扩展到反推路径
    "CAP-4d8ba002": (
        "LLM 图像提示词双向转化（扩写 + 反推）",
        "以大语言模型（ChatGPT/Claude/Gemini/DeepSeek/GPT-4V）为中间层，"
        "**扩写**方向：将用户简短关键词或模糊创意意图自动扩展为结构化、高质量的图像生成提示词；"
        "**反推**方向：对参考图像进行语义分析，自动提取色彩、构图、风格、镜头、布光、材质等维度的结构化提示词；"
        "实现从语义意图到可执行提示词、从视觉参考到文字描述的双向自动转化。"
    ),
    # [20] 扩展到故事文案/漫画/叙事排序
    "CAP-da51c2ec": (
        "AI 脚本/分镜/故事文案与叙事顺序生成",
        "根据用户输入的主题、关键词、拟人化角色或故事梗概，由 LLM 自动生成结构完整的脚本与分镜文案，"
        "涵盖动画脚本、短视频分镜、漫画分镜、情感叙事故事、绘本故事文案、剧本分页文字等多种载体。"
        "输出内容包含每格画面的场景描述、情绪标注、镜头语言、对白/旁白、叙事逻辑（起承转合）与叙事顺序规划，"
        "为后续图像/视频生成提供结构化提示词输入。"
    ),
    # [24] 扩展到主题色系 + HEX 约束
    "CAP-2bd87e28": (
        "主题色调系统约束生成（prompt 驱动）",
        "通过在提示词中指定主导色调（单一色相锁定：深蓝、赤红、暖色、金色、冷色）或完整的主题色彩系统"
        "（主色 + 辅助色 + 强调色，HEX/HSL 参数），"
        "配合光源描述、饱和度和背景处理关键词，使生成图像的整体色彩严格围绕指定方案，"
        "形成沉浸式的单色调氛围或系统一致的品牌色彩表达。"
    ),
    # [27] 扩展到互补色/对比色/双色对撞
    "CAP-2de278d6": (
        "高饱和多色并置与互补/对比色张力控制",
        "在图像生成过程中，通过精确的色彩参数化控制（多高饱和度色值、色相对比关系、色块分布比例），"
        "指定互补色对（complementary color pairs）、高对比色组合或双色对撞分区结构（对角分屏、红蓝对立），"
        "使画面呈现最大色彩纯度与最大色相张力，产生迷幻、震撼、多巴胺式的视觉冲击。"
    ),
    # [30] 具体化微纹理 + 次表面散射
    "CAP-3b0de1ce": (
        "超写实人像去 AI 感（皮肤微纹理 + 次表面散射 + 光线结构化）",
        "通过将皮肤视为物理材质而非美化效果、将光线视为空间结构而非氛围装饰，"
        "在提示词中明确加入皮肤微纹理描述（毛孔、绒毛、细纹、雀斑、轻微不对称、油性高光、微瑕疵）"
        "与次表面散射（Subsurface Scattering）参数，并通过专项皮肤增强工具进一步细化，"
        "从根本上消除 AI 生成人像的过度光滑、油腻、塑料感，使生成结果达到真实摄影级自然质感。"
    ),
    # [31] 重大扩展：加叙事分镜/漫画/表情矩阵
    "CAP-306c15fe": (
        "AI 一次生成多格网格图（姿态/分镜/漫画/表情矩阵）",
        "通过结构化提示词（JSON 格式或自然语言，指定 layout/subject/expressions/lighting/color_tone 等字段），"
        "驱动 AI 模型一次性生成包含多个分区的完整网格大图。支持多种用途：同一主体的多姿势/多角度/多场景矩阵、"
        "多格分镜叙事（起承转合）、多格漫画故事板、表情包 9 宫格、Bento Grid、非对称布局等，"
        "整体输出为单张图像，风格/色调/角色外观在格间保持统一，无需后期拼接。"
    ),
    # [34] 扩展到撞色方案/参考图提取/推荐
    "CAP-689bac61": (
        "色彩配色方案生成与推荐",
        "基于色彩理论（对比色、互补色、邻近色、三色组合、渐变过渡色）、内容主题、情感氛围或参考图输入，"
        "自动生成或推荐协调的配色方案（主色 + 辅助色 + 强调色，附 HEX/RGB 色值），"
        "涵盖产品摄影、海报、图文排版、品牌物料等场景。"
        "支持参考图语义分析与 HEX 色板自动提取（从图像提取 5 个核心色值渲染为调色板）。"
    ),
    # [35] 扩展到长文分页 + 社交媒体无缝横幅
    "CAP-20409fa6": (
        "AI 多页轮播/长文分页/社交媒体序列生成",
        "以主题、语气、长文内容或多张素材为输入，AI 自动完成内容拆分、版式匹配、图文合成，"
        "输出多页轮播/幻灯片、长文分图片序列（按段落分页、自动加页码）、"
        "数字剪贴簿、社交媒体无缝横幅拼接（多帖子在个人主页网格中连续成大图）等多种序列形态，"
        "所有页面视觉风格统一，适配社交平台比例一键发布。"
    ),
    # [36] 加物理光照
    "CAP-5fb6dd66": (
        "室内多光源分层与物理光照提示词工程",
        "在提示词中分层描述室内多光源组合（自然窗光/日光、吊灯、筒灯、射灯、落地灯/台灯、隐藏灯带），"
        "并指定光源类型、方向、色温、光质（漫射/定向/体积光束）以及物理行为（环境遮蔽、接触阴影、自然反弹、"
        "由近到远的光影渐变），生成具有丰富光影层次与物理正确感的室内效果图。"
    ),
    # [38] 加有机形态元素
    "CAP-56368e3a": (
        "室内自然材质纹理与有机形态精准生成",
        "在室内效果图生成中，精准还原藤编、实木（胡桃木/榆木/橡木）、大理石、宣纸肌理、竹编、棉麻、亚麻"
        "等天然材质的视觉纹理特征，并控制弧形、拱形、圆润等有机形态设计元素，"
        "使画面传达自然、温润、生活化的治愈氛围，区别于冷硬工业风或过度精致的奢华风。"
    ),
    # [39] 扩展到综合写实
    "CAP-aaaef688": (
        "电影级光照与写实质感提示词工程",
        "通过提示词引入电影摄影的专业光照术语与写实质感维度："
        "光照（golden hour lighting 黄金时段、cinematic lighting 电影级照明、editorial lighting 编辑级照明）、"
        "摄影参数（景深、镜头角度）、材质细节（毛发纹理、皮肤质感）、场景氛围（色彩分级、环境光）"
        "的综合组合策略，系统化提升 AI 生成图像的戏剧性、艺术性和照片级真实度。"
    ),
    # [41] 去掉科技感，泛化
    "CAP-5b000814": (
        "结构化 Prompt 框架工程（分段/模板/参数化）",
        "系统化设计 Prompt 的分段结构（SUBJECT / ENVIRONMENT / MOOD / COLOR LOGIC / CAMERA / SCENE / LIGHTING / QUALITY 等维度），"
        "使 AI 模型能够分维度理解并精确控制图像；并将验证过的高质量 Prompt 框架抽象为可复用模板，"
        "通过替换变量（主题、国家、产品、风格词等）批量生成风格统一的系列化内容，"
        "实现 AI 生成输出的可复现精准风格控制。"
    ),
    # [43] 扩展到人体局部
    "CAP-26100ea8": (
        "微距/极端特写构图与画幅填充控制",
        "通过提示词中的镜头参数（macro lens、micro lens、close-up、extreme close-up）"
        "与构图指令（主体占满画幅、fill the frame、极端裁切），"
        "精确控制 AI 生成图像中主体（人体局部：眼部/嘴部/手部/指甲/耳部；或产品/物件/食物截面）"
        "的放大比例、裁切范围与焦点区域，生成画面填充感强、主体突出的微距/特写图像。"
    ),
    # [45] 重大扩展
    "CAP-562d91c1": (
        "海报/长图多元素自动排版与版式智能设计",
        "通过 AI 设计工具或生成式排版引擎，将多种异质视觉元素（人物照片、品牌 Logo、活动标识、二维码、"
        "数据图表、时间线、流程图、文字段落、装饰元素、地图、产品照片）按照信息层级、品牌规范和视觉平衡原则，"
        "自动选择最优构图方案（居中、左右、对角、时间轴、戏剧性垂直分割、三角形/X 形），"
        "并按信息优先级分配视觉权重，合成为专业商业海报、信息图或杂志/报告风格的完整长图版面。"
    ),
    # [46] 加分层景深语言
    "CAP-3c49ff0a": (
        "空间透视与多层景深提示词精确控制",
        "通过在提示词中精确指定消失点类型（一点/两点/三点透视）、视平线高度、相机视角（低角度/眼平/俯视），"
        "分层描述前景/中景/背景各层元素（实焦/虚化、高斯模糊、大气透视），"
        "建筑框景元素（拱门/窗框/门洞/柱廊/地板线条向消失点汇聚/纹理拼接角度）以及镜头参数（广角/超广角），"
        "或通过 ControlNet 深度图约束，生成具有强烈空间纵深感、三维立体景深和史诗级空间规模感的画面。"
    ),
    # [49] 扩展到光晕/泛光/流光线条
    "CAP-a35e7966": (
        "霓虹/光晕/泛光/流光发光效果生成",
        "在 AI 生成图像中通过提示词参数或后处理节点，为文字、轮廓线、场景元素、光源周围"
        "（灯笼/路灯/窗灯/月亮等深色背景光源）添加多种发光效果：霓虹管状发光、外发光晕、光晕 Halo、"
        "泛光 Glow、光芒扩散、多层渐变光晕、流光线条、粒子散射、渐变镭射，"
        "营造赛博朋克/科技感/深色氛围的发光视觉质感。"
    ),
    # [51] 加孔版印刷/波普网点
    "CAP-9359b49f": (
        "复古印刷质感与半色调/孔版/波普纹理生成",
        "通过 AI 生成或后处理节点，模拟复古印刷工艺的视觉质感："
        "丝网印刷、半色调网点（Halftone）、孔版印刷（Risograph）、波普艺术网点与几何光学错觉纹理、"
        "混合模式叠印、颜色分层叠印、油墨渗透扩散，"
        "在高饱和色彩画面上叠加颗粒噪点、做旧肌理和色彩分离效果，"
        "使画面呈现强烈的年代感与手工印刷质感。"
    ),
    # [53] 扩展到3D透视+场景表面融合
    "CAP-bd4828fc": (
        "文字透视变形与场景表面 3D 融合",
        "对叠加或生成的文字应用三维透视变形（梯形、弧形、斜向排列、曲面贴合、消失点对齐），"
        "使文字随场景物体表面（建筑、桥梁、地面、墙面）产生渐进压缩、深度衰减和空间透视关系，"
        "形成文字融入场景的氛围感效果（而非漂浮叠加），广泛用于照片加字、创意 P 图、场景海报风格。"
    ),
    # [54] 泛化到非人类主体
    "CAP-e962c3ef": (
        "非人类主体拟人化角色形象构建",
        "通过结构化提示词工程，为非人类主体（动物如猫咪、玩具、机器人、材质实体等）赋予完整的人类角色属性——"
        "职业身份、服饰道具（帽子、厨师服、僧袍、背带裤、球衣、蝴蝶结）、面部表情、肢体姿态与背景故事，"
        "并使其与道具（书本、购物篮、玩偶）产生自然交互。"
        "保留物种/材质本体特征（毛色、外形、质感），实现角色扮演级的拟人化视觉表达。"
    ),
    # [56] 扩展到环境粒子 + 主体联动
    "CAP-8467736a": (
        "粒子光效与环境特效场景生成",
        "通过 AI 提示词或专业 3D/特效工具，生成大量发光粒子（星点、尘埃、能量球、光束）或环境粒子"
        "（尘土飞扬、烟雾弥漫、水花飞溅、花瓣飘落）在场景中流动、汇聚、爆发或与主体运动物理联动的视觉效果。"
        "粒子具有多种颜色（橙、蓝、紫、金等）与自发光属性，形成梦幻/魔幻氛围或强化主体动感与临场感。"
    ),
    # [57] 明确加蓝调时刻
    "CAP-e8a77f70": (
        "自然光照与特定时刻氛围生成",
        "生成具有真实自然光照效果的图像，涵盖柔和自然光、金色时刻（Golden Hour，日出后/日落前约 1 小时，"
        "温暖橙金色调）、蓝调时刻（Blue Hour，日落后约 20 分钟，清冷蓝紫色调）、"
        "日落暖光、阴天柔光、室内窗光等真实光照条件，"
        "并配合斑驳树影、水面反光、晨雾等自然光效果，营造特定情绪氛围。"
    ),
    # [58] 扩展到非伦勃朗类（丁达尔/黄金逆光/窗户光/影棚柔光）
    "CAP-ed4b506e": (
        "人像专业布光模式精准复现",
        "通过在提示词中使用专业摄影布光术语，精准复现经典或氛围性布光模式："
        "伦勃朗光（Rembrandt）、蝴蝶光（Butterfly）、侧逆光（Rim Lighting）、二分光（Split Lighting）、"
        "丁达尔光晕、黄金时刻逆光、窗户光、影棚柔光箱、光比与光源方向控制，"
        "使生成人像呈现专业摄影棚级别的光影结构、面部立体感与情绪氛围。"
    ),
    # [61] 泛化到任意场景
    "CAP-a95da8d7": (
        "AI 文生视频 / 动画帧序列生成",
        "基于文本描述或参考图像，使用新一代 AI 文生视频模型（Seedance、Veo、Kling 等），"
        "通过结构化提示词直接生成具有时间连贯性的动画帧序列或完整视频片段，"
        "涵盖从静态氛围场景（夜景、日间、室内外）到动态运动内容的多种主题，"
        "将静态描述或插画的情绪氛围转化为具有时间维度的电影级动态视觉叙事。"
    ),
}


def main():
    ap = argparse.ArgumentParser()
    g = ap.add_mutually_exclusive_group(required=True)
    g.add_argument("--dry-run", action="store_true")
    g.add_argument("--execute", action="store_true")
    args = ap.parse_args()

    dry = args.dry_run
    print(f"\n{'='*60}\n{'DRY RUN' if dry else 'EXECUTE'} — 更新 canonical name/description（{len(RENAMES)} 条）\n"
          f"{'='*60}\n", flush=True)

    store = PostgreSQLCapabilityStore()
    cur = store._get_cursor()
    try:
        updated = 0
        for idx, (cid, (new_name, new_desc)) in enumerate(RENAMES.items(), 1):
            cur.execute("SELECT id, name, description FROM capability WHERE id = %s", (cid,))
            r = cur.fetchone()
            if not r:
                print(f"[{idx}] {cid} ⚠️  NOT FOUND", flush=True)
                continue
            print(f"[{idx}] {cid}", flush=True)
            print(f"    old name: {r['name']}", flush=True)
            print(f"    new name: {new_name}", flush=True)
            if r['description'] != new_desc:
                print(f"    desc will be updated ({len(r['description'] or '')} → {len(new_desc)} chars)",
                      flush=True)
            if not dry:
                cur.execute(
                    "UPDATE capability SET name = %s, description = %s WHERE id = %s",
                    (new_name, new_desc, cid),
                )
                updated += 1
            else:
                updated += 1
        print(f"\n{'='*60}\n{'[DRY] 将' if dry else '已'}更新 {updated} 条 canonical\n{'='*60}\n",
              flush=True)
    finally:
        cur.close()
        store.close()


if __name__ == "__main__":
    main()