trip-moments-skill 1.0.0

package/.agents/skills/trip-moments/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: trip-moments
+description: 朋友圈旅游出图助手——旅行照片九图优选、AI 修图、批量裁剪、九宫格拼图、高德旅行路线图、杂志风海报、朋友圈文案。只要用户提到发朋友圈、九宫格、选图/挑图/选九张、修图/精修/去路人、旅游/旅行照片、路线图/行程地图、出片、vlog 封面、旅行文案,即使没说"朋友圈"二字也应触发。
+---
+
+# trip-moments · 朋友圈旅游出图助手
+
+技能脚本目录:本 SKILL.md 所在目录下的 `scripts\` 子目录(下文用 `<S>` 指代;经 install.cmd
+安装后位于用户级 skills 目录,直接取本文件同级的 scripts 即可,不要写死绝对路径)。
+所有命令用 `python <S>/<脚本>.py ...` 运行;Windows 上若无 `python` 命令改用 `py -3`。
+
+## 快速安装与分发
+
+- **一键安装/更新 (npx 模式)**:
+  `npx trip-moments-skill@latest` (国内镜像: `npx --registry=https://registry.npmmirror.com trip-moments-skill@latest`)
+- **本地源码开发**:
+  `python -m pip install -r <S>/requirements.txt` 然后运行 `install.cmd` / `install.ps1`。
+
+## 第一步:环境自检(每次会话一次,别反复跑)
+
+1. 依赖:运行任一脚本 `--help`,若报 `ModuleNotFoundError` 则
+   `python -m pip install -r <S>/requirements.txt`;pip 找不到 numpy(网络截断)时,
+   见仓库 README"疑难排查"——用镜像 wheel 本地装。
+   ——模型名过期(如换了网关后残留旧模型)会当场报 `MISMATCH` 并给出修复命令,
+   避免跑到一半才炸。有 issue 就把修复命令给用户,修完重跑确认。
+3. **修改任何脚本代码后,跑 `python <S>/selftest.py`**:11 项离线纯逻辑断言
+   (变体名归一/显著性死区/主体锚点/纠偏/预设完整性/错误指引等),零网络零计费,
+   全绿再交付;红了就先修,不要把坏的代码交给用户验证。
+3. 渠道优先级(aiclient.py 已内置,无需手动切换):自建网关(`TRIP_AI_*`/`OPENAI_*`,
+   配了即视为有意使用)→ 硅基流动 → 智谱(不能修图)→ 百炼(只修图)。
+   **模型名不设也行**:网关可用时,VL/EDIT/T2I 会自动从网关 `/models` 在售列表按偏好
+   挑选(识图优先 flash-high 系,修图/生图优先 gemini 图像系——对话模型本身能识图
+   生图时完全不需要外置模型);`TRIP_VL_MODEL` 等仅在你想锁定特定模型时才设置。
+   缺 key **不阻塞本地功能**;需要哪个就把 `references/api-config.md` 的申请步骤
+   和 `setx` 命令给用户,不要替用户设 key 的值。
+
+## 交互节奏(优先级高于一切工作流规则)
+
+一次跑完整条链是大忌:用户要的是**一步一步来、每步都能插手**。
+
+- 每出一个可见产出(候选清单、一张试修图、一版文案、一张卡片)就**停下来**,
+  用一句话说清"这是什么 + 建议的下一步",等用户表态再继续,绝不自动连跑下一步
+- 提问用**选择题式**(2-4 个选项并给出你的推荐),不要甩开放式问题让用户填空
+- 三件事必须先问再做:① 任何 AI 计费操作(报张数与预计花费)② 批量编辑前先试修
+  1 张给用户看过效果 ③ 涉及人物/审美的指令,先复述你的理解让用户确认
+- 纯本地、免费、可逆的小步骤(如按预设裁剪)做完直接展示即可,不必每步请示;
+  用户不满意就改参数重跑,告诉他这是免费随便试的
+- 只有用户明说"你看着办"才允许连跑,跑完仍要逐步汇报每步产物
+
+## 输出约定(所有工作流遵守)
+
+- 产物统一写入照片目录旁的 `trip-moments-output\` 子目录,**绝不覆盖原图**
+- 完成后向用户列出产物路径(用 Markdown 链接),并简要汇报选择/设计理由
+- AI 按张计费:任何 AI 批量调用前,先告诉用户"将调用 N 张、模型 X",征得同意再跑
+
+## 工作流
+
+### 0. 识别与找图(用户说"找出有XX的照片/把XX修一下/这些都是什么")
+
+```bash
+python <S>/findphotos.py "<照片目录>" --has "红头发的男孩" [--not-has "自拍"]   # 找图
+python <S>/findphotos.py "<照片目录>" --describe                              # 全量识别打标
+```
+
+- 一次丢几十张也没问题:每 5 张缩略图一批送视觉模型,自动汇总
+- `--has`:命中照片复制到 `trip-moments-output\find\<标签>\` + `find.json`(含置信度和理由),
+  末尾会打印接 retouch.py 的下一条命令
+- `--describe`:输出 `describe.json`(每张的场景/人物/物品/氛围),写文案、选图、
+  找人都先读它
+- 需要任一 AI 服务商 key;无 key 时明确告知,本地无法做识别
+
+### 1. 九图优选(用户说"帮我选 9 张 / 挑图 / 九宫格用哪几张")
+
+**先做 10 秒小问卷**(用户没说"你看着办"时必问,选择题式,一次问完):
+
+1. 这组九宫格的主角是什么?——人物为主 / 风景为主 / 美食烟火 / 建筑街景 / 混着来
+2. 更吃哪种排布?——色调统一显高级 / 场景多样像游记
+3. C 位(第 5 张)有指定想放的照片或主题吗?
+
+把答案拼成一句偏好传入 `--prefer`(如 `--prefer "人物为主,人像清晰优先,C位放合影"`);
+质量相近时评分模型会向偏好倾斜,describe.json 存在时还按标签软加权(没有可先跑
+工作流 0 的 `--describe`,加了权也不硬过滤废片)。
+
+```bash
+python <S>/select9.py "<照片目录>" -n 9 --prefer "<问卷结论>"
+```
+
+- 有任一 AI 服务商 key 时自动加视觉模型评分(美感/构图/场景),并保证场景多样性;
+  没有则纯本地打分(清晰度/曝光/分辨率/去重),都会自动跳过重复废片
+- 产物:`selected9\01_原名.jpg...`(**编号 = 九宫格位置**,从左上到右下,发布时按编号
+  顺序点选即可)+ `selection.json`(含每张主色与色调统一度)
+- 位置讲究(大众经验):01 左上是"开场位"决定第一眼,**05 是 C 位**放最想展示的,
+  09 右下收尾;脚本已按此排布,C 位那张要点名告诉用户
+- 汇报时读 selection.json:按位置报每张的入选理由(总分/硬伤),被挤掉的图里
+  有用户可能想要的主动提一句
+- **然后停下来问**:顺序要不要调?有必须保留/必须踢掉的图吗?改完确认后,
+  再问"要顺手裁成 3:4 吗"
+- 数量讲究:高质量照片凑不满 9 张时,**建议发 3 张或 6 张**而不是硬凑
+  (1/3/6/9 是朋友圈常见节奏);色调分散时提示"统一滤镜或换图会更高级"
+- 用户想调整时:可以让他指定"必须保留 XX",你改用 `--no-ai` 后人工挑选,
+  或直接对 selected9 增删
+
+### 2. AI 修图(用户说"修图/精修/去路人/改成胶片风")→ 需任一图像编辑渠道(网关 / 硅基流动 / 百炼)
+
+```bash
+python <S>/retouch.py "<照片或目录>"... -p "<指令>" [-f edit|erase|expand|style|colorize|upscale] [--provider auto|dashscope|openai]
+```
+
+- **针对特定人物的编辑**(如"把红头发男孩修瘦一点"):先用工作流 0 找出命中照片,
+  **展示命中列表让用户确认**,再对命中目录执行编辑——绝不能把人物指令盲刷到全部照片
+  (没有该人物的照片会被浪费计费且效果不可控)
+  ```bash
+  python <S>/findphotos.py "<目录>" --has "红头发的男孩"
+  python <S>/retouch.py "<目录>\trip-moments-output\find\红头发的男孩" -p "让画面里红头发的男孩看起来瘦一点,背景和其他人物保持自然不变"
+  ```
+- 指令里写清**保留什么**:"只动XX,背景/其他人/构图不变",编辑模型更稳
+
+- provider auto:显式网关优先(gpt-image 系自动走原生 multipart `/images/edits`,
+  gemini 图像系自动走 chat 图进图出),其次百炼预设(expand/upscale 仅百炼支持),
+  再硅基流动 Qwen-Image-Edit;模型可用 `TRIP_EDIT_MODEL` 覆盖
+- 常用指令:`去掉画面中的游客,保持背景自然` / `调成日系胶片色调,轻微颗粒` /
+  `把天空换成干净的黄昏色,其余不变`
+- 先确认张数再执行(计费);产物在 `trip-moments-output\retouched\`
+- 失败排错看 `references/ai-apis.md`(各家请求格式、常见错误码)
+- 无 key 或用户不想花钱:如实说明"AI 修图需要配置 AI 服务商",本地可做的只有裁剪(crop.py),
+  调色建议手机编辑器处理
+
+### 3. 构图重调 + 批量裁剪(常与 1/2 组合)
+
+**不要默认"裁成 3:4"**,也不要"逢图必裁"——**不为裁而裁**:构图已经成立的
+照片原样保留,只有裁切能明显改善(干扰物、比例不适配、主体被削弱)时才动刀。
+默认流程是"先构图重调,再决定裁不裁":
+
+```bash
+# AI 构图建议:一次调用给全部照片逐张判断"裁不裁、裁成什么比例"+取景思路(计费 1 次视觉调用)
+python <S>/crop.py "<照片目录或 selected9>" --ai-compose
+# 用户明确要固定比例/全部比例时才用:
+python <S>/crop.py "<目录>" --ratio 3:4 --width 1080
+python <S>/crop.py "<目录>" --all
+```
+
+- `--ai-compose`:视觉模型一次调用完成三件事——逐张定比例(1:1/3:4/4:3/16:9/9:16
+  或 **不裁**)、给取景理由、**标注画面主体中心坐标**;构图已成立的照片原样保留
+  (**不为裁而裁**),需要裁的窗口强制包含主体(人像绝不被切半),
+  显著性算法(细节/肤色/饱和 + 死区排除 + 三分法)只在主体约束内微调
+- **自动审核回环**:裁完自动把"原图 vs 裁切结果"成对送视觉模型复审(主体完整?
+  构图成立?),不合格的自动按主体中心重裁再交付——但复审可能误报
+  (如幻觉"拉伸变形"),refit 结果要肉眼抽检再交给用户
+- 无论哪种比例,取景都尊重显著性;汇报时把每张的建议理由念给用户,不认可就单张重跑
+- 朋友圈建议:竖图 3:4、正方 1:1;横图发布时会被裁,重要内容居中
+
+### 4. 九宫格拼图(用户说"拼成一张九宫格")
+
+```bash
+python <S>/grid9.py "<目录或9张图>" [--cols 3 --rows 3 --size 1080 --gap 10 --bg #ffffff]
+```
+
+- 取前 cols*rows 张;产物 `trip-moments-output\grid9.jpg`
+- 每格按 cell 比例智能取景(smart_crop);若输入目录有 `compose.json`
+  (`crop.py --ai-compose` 自动写出的主体坐标),**优先用 AI 锚点取景**——
+  方形格里桥/人/塔不会被切丢。九宫格前跑过 AI 构图的,直接拼即可
+
+### 5. 旅行路线图(用户说"做个路线图/行程图")→ 需 AMAP_KEY
+
+```bash
+# 文字行程:先把用户的行程整理成逗号分隔的地点(含城市前缀消歧义)
+python <S>/route_map.py --stops "上海,乌镇,杭州西湖" --days "D1,D2,D3" \
+    --title "江南三日" --subtitle "2026.05.01 - 05.03"
+# 照片轨迹:先 EXIF 提取再画
+python <S>/exif_gps.py "<照片目录>"
+python <S>/route_map.py --gps "<照片目录>\trip-moments-output\gps.json" --map-only --title "环岛骑行"
+```
+
+- 产物:`trip-moments-output\route-map\route-card.jpg`(1080x1440 竖卡,含编号图钉、
+  虚线路线、标题、站点列表)+ `map.png` + `route.json`
+- 地点写法给用户的示例:"上海" 可能歧义时用 "上海虹桥" "杭州西湖"
+- **出图前先把你解析出的站点列表亮给用户确认**(地名、顺序、Day 标签),确认后再调 API
+- 无 key:给 api-config.md 的高德申请步骤;可先跑 `--dry-run --coords` 预览计算结果
+- 排错看 `references/amap-geo.md`(key 类型必须是"Web服务")
+
+### 6. 杂志风海报(用户说"做成海报/杂志封面风")
+
+```bash
+python <S>/poster.py "<照片>" [--title "<你写的标题>"] [--subtitle "SEASIDE · 2026"] [--mode local|panel|full|auto]
+```
+
+- **模式**(auto 默认:能修图就 full,否则 panel,再退 local):
+  - full(首选):整张一次生成——照片区+抽象记忆面板+标题由模型排好,
+    实测 gemini-3.1-flash-image 效果最佳(主体解构准、颜色全有源、无乱码),
+    gpt-image 系列亦可;Qwen-Image-Edit 会重绘照片并产生乱码文字,不要用它跑 full
+  - panel:AI 看照片只画抽象画板(照片与标题本地精确排版,无乱码文字风险;
+    无图像输入模型时退回只喂主色的文生图画板)
+  - local:免 key,纯本地绘制
+- **标题**:--title 省略时由视觉模型看照片原创诗意英文标题(2-5 词,信达雅);
+  自己写的话读 `references/editorial-poster.md` 的规则,给用户 2-3 个候选确认
+- 产物:`trip-moments-output\poster\poster_<名>.jpg`(1080x1440)
+- 效果样张:`assets/examples/editorial-bridge-gemini.png`(gemini-3.1-flash-image full)
+
+### 7. 风格出片(用户说"做成拍立得/电影感/杂志封面/手帐/贴纸/水墨")
+
+```bash
+# 免费本地,内容零改动:
+python <S>/polaroid.py "<照片>" --caption "塔前留影 · 2026夏"   # 拍立得白框+手写体+旋转阴影
+python <S>/film.py "<照片>" --caption "城堡烟花 · 上海迪士尼"     # 电影宽幅+青橙调+颗粒+字幕
+python <S>/poster.py "<照片>" --title "Slow Tide"                 # 杂志海报(见工作流 6)
+python <S>/enhance.py "<目录>"                                    # 批量轻美化(免费)
+# AI 风格化(每张计费,先试 1 张再批量):
+python <S>/styles.py "<照片>" --style magazine --title "把日子过成诗"
+python <S>/styles.py --list   # magazine杂志封面 / journal旅行手帐 / sticker 3D贴纸 / ink国风水墨 / cine电影感
+```
+
+- 文案元素(--caption/--title)由你按照片内容撰写,别用默认值凑数
+- 本地系(polaroid/film/enhance/poster-local)零成本随便试;styles.py 单张约几毛,
+  批量前按交互规则先给用户看 1 张样张
+- **人脸安全网**:retouch/styles 每次编辑后自动跑人脸完整性检查(原图 vs 成图,
+  视觉模型判定"是否同一人/是否畸变"),不通过会打 `[!!]` 警告——**必须把警告原样
+  转达用户并建议弃用该张**;人像多的用户提示他们:重绘类 AI 风格有崩脸风险,
+  想保脸用本地系或加"面部完全不变"指令,`--no-face-check` 可跳过检查
+
+### 8. 朋友圈文案(几乎每次都顺手做)
+
+由你直接撰写(不调 API),依据:selection.json / describe.json 的场景标签、行程、用户语气偏好。
+**一次给三个版本让用户挑**(不要自己拍板),输出到 `trip-moments-output\caption.md`;
+**同时另存一份 `captions.json`**(数组,三个版本各一条)——工作台 review.py 会读它把文案
+显示在页面里并支持一键复制,只写 md 会导致页面上永远显示"未生成"。
+
+- **克制版**:一两个短句 + emoji ≤2 个,不堆砌形容词
+- **文艺版**:一个具体画面细节开头,可一句轻感悟,不无病呻吟
+- **活泼版**:口语化,可用 1-2 个梗,不加一长串话题标签
+
+示例(克制):`三天,两个古镇,一场没赶上的日落 🌇`
+
+### 9. 本地工作台(每完成一个阶段跑一次,给用户一个可视总览)
+
+```bash
+python <S>/review.py "<trip-moments-output 目录>"        # 生成 review.html(默认 --pool 取上级目录)
+python <S>/review.py "<目录>" --pool "<原始照片目录>" -o "<目录>/review.html"
+```
+
+单文件静态页,双击/预览即开,零依赖零常驻服务。包含:阶段状态条(优选/构图/美化/文案/地图)、
+九宫格成品卡片(分数+AI 评语+裁/美/AI 徽章)、原图vs裁切vs美化的拖杆对比、
+EXIF 行程地图(GCJ-02+高德瓦片,离线时自动回退)、文案展示(读 captions.json,支持一键复制)、
+候选池缩略图。文案写完时另存一份 `captions.json`(数组或 {versions:[...]})即可自动上页面。
+**每个阶段跑完都顺手重跑一次 review.py**,让用户在浏览器里看最新进展,代替刷屏发图。
+
+## 组合套路(用户没说具体步骤时,按此节奏推进;每步之间停下来等用户表态)
+
+- "帮我发朋友圈":① 九图优选(先做小问卷)→ 展示清单问意见 → ② 问三件事:
+  要修图吗(先试 1 张)?要免费美化吗(enhance)?裁剪按 AI 构图建议逐张定比例还是固定 3:4?
+  → ③ **主动把风格菜单摆出来问**:免费系(电影感/拍立得/轻美化)随便试;
+  AI 风格化(杂志封面/旅行手帐/3D贴纸/国风水墨)按张计费——用户挑了再跑
+  → ④ 文案三选一 → ⑤ 最后问"要配路线图或海报吗"
+- "这趟旅行出个片":先问清楚"海报 / 路线图 / 九图优选 / 风格出片 / 文案,要哪几个、
+  先做哪个",再逐个做
+- 任何时刻用户都可以改主意回到上一步;照片无 GPS 时主动说明路线图改用文字行程输入

package/.agents/skills/trip-moments/assets/photo-abstract-editorial/PROVENANCE.md

@@ -0,0 +1,6 @@
+# photo-abstract-editorial 提示词
+
+- 来源:https://github.com/ZzzLc0405/photo-abstract-editorial
+- 文件:references/photo-abstract-editorial-prompt.zh-CN.md(2026-09 拉取)
+- 许可:仅限个人、教育与非商业用途(见原仓库 LICENSE.md),禁止商用
+- 用法:styles.py --style editorial 将此提示词原样交给图像编辑模型执行

package/.agents/skills/trip-moments/assets/photo-abstract-editorial/prompt-zh.md

@@ -0,0 +1,246 @@
+将上传的图片严格作为唯一的内容来源和摄影原片使用。请生成一张由“原照片区域＋抽象记忆面板＋诗意标题”组成的完整编辑作品，而不是单独生成抽象画，也不是直接对照片应用滤镜。
+
+## 一、输入图片的角色
+
+上传图片是唯一的内容来源，同时承担两个角色：
+
+1. 摄影区域的原片  
+    在成品上方或主要区域忠实展示这张照片。保持其主体、建筑、人物、光线、颜色、空间关系和摄影气质。只允许为适应拼接比例进行克制的等比缩放或轻微裁切，不得重画、替换、扩展、修饰或改变照片内容。
+    
+2. 抽象面板的信息来源  
+    分析照片中的主体关系、大小比例、左右与上下位置、方向、曲线、水平轴、垂直轴、间距、重复、遮挡、前后层级、明暗层级、色彩角色和留白，再将这些关系重构为照片下方的抽象视觉记忆。
+    
+
+不得引入任何其他图片、场景、物体、颜色或象征。
+
+## 二、工作方法
+
+方法必须是：
+
+DECONSTRUCT → SELECTIVE PRESERVATION → ABSTRACT / DISTILL → RECONSTRUCT
+
+这不是风格迁移，也不是照片矢量化。
+
+先在内部完成以下判断，但不要输出分析文字：
+
+1. 找出照片中最重要的三至六个空间事实。
+    
+2. 判断哪些信息来自主体质量，哪些来自结构轴、运动方向、重复节奏、间隔、遮挡、非对称、色彩层级或留白。
+    
+3. 删除物体表面纹理、透视细节、背景杂讯和低信息装饰。
+    
+4. 用最少的标记重新组织被保留的关系。
+    
+5. 使抽象图形在第一眼呈现为极简抽象构成，在第二眼才使人联想到这张特定照片。
+    
+
+画面必须对应原照片独有的空间节奏，但不得成为照片缩略图、描摹、海报化照片、滤镜效果、完整插画或通用图标。
+
+## 三、抽象程度与主体辨识
+
+默认采用“关系优先、轮廓舍弃”的抽象方式，但根据照片主体自适应处理：
+
+- 普通场景、自然景观、光影、地平线、水面和人群：主要保留方向、密度、间隔、层级、运动和色彩关系，不保留完整物体轮廓。
+    
+- 标志性建筑或具有独特形状的主体：允许保留一至三个最低限度的身份特征，例如特殊外轮廓、代表性负空间、檐线、塔身收分、拱洞、尖顶或层叠节奏。不得描绘窗户、砖石、斗拱、雕刻、栏杆花纹等细节。
+    
+- 有机群体，如气球、树冠、云团或灯光：用相互重叠的柔和有机色块表达密度和上升、扩散或聚集关系，不绘制内部图案和写实高光。
+    
+- 人群：每个人只用一个连续、不规则的短竖墨点或轻微收分的色块表示。头肩与身体连成一体，不单独绘制圆形头部、四肢、面孔和衣服。通过高低、宽窄、间距、倾斜和前后遮挡形成节奏。
+    
+- 栏杆、道路、地平线或水岸：压缩为一至两条细水平轴和少量不规则中断。
+    
+- 小型代表性物件，如铃铛、灯笼或风铃：只保留两至三个平面标记。通过比例和位置建立辨识，不使用金属高光、真实体积、内部结构或写实材质。
+    
+
+原则是：保留“最低必要辨识度”，而不是复刻物体。
+
+## 四、标记系统
+
+使用一个主要标记家族，最多两个辅助标记家族。
+
+主要标记可从以下形式中选择一种：
+
+- 平面或微有机色块
+    
+- 柔和圆形或不规则质量
+    
+- 弧形或锥形笔触
+    
+- 连续短条或层叠色带
+    
+- 简化建筑质量
+    
+
+辅助标记最多选择两种：
+
+- 细线或结构轴
+    
+- 短竖条、孤立小点或微型轮廓
+    
+- 克制的人影墨点
+    
+- 少量重复节奏
+    
+
+每一个标记都必须能对应原照片中的一个事实。不得为了“好看”加入没有来源的装饰、对称、图案、颜色或物体。
+
+避免规则化间距。相邻标记应存在轻微尺度差、位置差和停顿，使其具有观察所得的自然节奏，而不是信息图表或矢量图标。
+
+## 五、照片与抽象面板的自适应拼接
+
+生成一张完整的竖向编辑作品，由上方摄影区域和下方象牙色抽象面板组成。
+
+不得机械地采用上下各占一半。应根据原照片方向、主体密度、视觉重心和留白状况，自适应决定拼接比例：
+
+- 横向照片或具有强烈水平延展的照片：摄影区域约占成品高度的 38%–52%，抽象面板约占 48%–62%。
+    
+- 纵向建筑、人物或高耸主体照片：摄影区域约占 55%–68%，抽象面板约占 32%–45%。
+    
+- 接近方形或视觉重心均衡的照片：摄影区域约占 48%–58%，抽象面板约占 42%–52%。
+    
+
+以上比例允许根据实际画面上下浮动约 8%，以整体协调为最高原则。
+
+摄影区域保持原图宽高关系，优先完整呈现主体；不得为了固定比例进行激进裁切。最终画布比例应由原照片比例和面板高度共同决定，不强制使用 1:1、3:4 或固定的上下等分结构。
+
+照片与面板之间采用干净、直接、无阴影的平面衔接。不得使用撕纸边缘、相框、投影、立体卡片、胶带、拼贴阴影或样机效果。
+
+## 六、抽象面板版式
+
+抽象面板背景必须是完全均匀、连续、无断裂的中性象牙色：
+
+#F3F0E8  或是其他同色系的颜色，但要和抽象主体搭配和谐
+
+抽象母题放置在面板的中下部、中央附近或由原照片关系支持的非对称位置。
+
+默认尺度：
+
+- 母题占面板宽度约 30%–42%。
+    
+- 高度通常不超过面板高度的 28%–34%。
+    
+- 保留约 65%–80% 的干净空白。
+    
+
+根据主体类型允许调整：
+
+- 细长地平线、桥梁、道路或横向人群可扩展到面板宽度的 45%–68%，但必须保持较低高度。
+    
+- 标志性高层建筑、塔或纵向主体可增加高度，但不得填满面板。
+    
+- 紧凑有机群体应保持聚集，不得散落到整张面板。
+    
+- 不要为了满足百分比把母题缩成失去内部关系的通用小图标。
+    
+
+母题内部的大小关系、方向、间距、遮挡、重复、重心和非对称必须作为一个整体保留。
+
+## 七、色彩系统
+
+只从原照片中提取颜色，并将其降低饱和度、减少数量。
+
+使用原则：
+
+- 一个主色角色。
+    
+- 一个深色结构角色。
+    
+- 一个浅色或中性色角色。
+    
+- 最多一个至两个小面积强调色。
+    
+
+强调色只能来自照片中真实存在的重要颜色，并且只能用于少量关键标记。
+
+不得增加霓虹色、无来源的互补色或多种竞争性强调色。
+
+## 八、标题命名
+
+根据照片主体、空间关系、时间、光线、运动和情绪，在内部创作一个原创英文标题。
+
+标题必须做到“信、达、雅”：
+
+- 信：能够对应照片中真实存在的主体关系或视觉事实。
+    
+- 达：简洁、自然、可理解，不使用生硬翻译。
+    
+- 雅：具有诗意和余韵，但不过度煽情、晦涩或故作深沉。
+    
+
+标题优先使用 2–5 个英文单词，可采用以下命名方向之一：
+
+- 光线或时间进入某个空间
+    
+- 两个主体之间的关系或对话
+    
+- 某种短暂出现、漂浮、远去或停顿
+    
+- 从照片颜色、结构轴或运动趋势中提炼出的隐喻
+    
+- 一个原创复合词加简短说明
+    
+
+避免旅游宣传式标题、地点介绍、摄影术语、空泛的“Memory”“Dream”“Moment”，以及与照片事实无关的宏大叙事。
+
+默认只生成一个主标题。
+
+仅当副标题能够增加新的语义层，而不是重复主标题时，才允许加入一个 3–7 个英文单词的短副标题。主标题与副标题均只出现一次。
+
+先在内部确定最终标题，再将其准确渲染。不得生成候选标题、解释文字或其他文案。
+
+## 九、标题排版
+
+标题只能放在象牙色抽象面板内，位于抽象母题下方或侧边，具体位置应当参考两侧留白和整体协调情况。
+
+在以下两种布局中自适应选择：
+
+1. 左下对齐  
+    适用于母题居中偏右、横向延展或整体重心偏右的画面。此时标题可以考虑竖版或横板，标题距左边和底边保留约 6%–9% 的安全距离。
+    
+2. 底部居中  
+    适用于母题基本居中、轴线明确、建筑对称或上下呼应的画面。标题与母题中心轴保持协调，但不要贴近母题。
+    
+
+不得把标题放到照片区域、母题内部、右下角或画布边缘。
+
+字体规则：
+
+- 英文主标题使用优雅、克制、带编辑感的衬线字体。
+    
+- 建筑、城市和结构性题材可使用稳重的书籍衬线体。
+    
+- 光影、自然和抒情题材可使用略带人文感的细衬线体。
+    
+- 副标题如存在，可使用尺寸更小的优雅斜体衬线。
+    
+- 不使用商业粗体、无衬线广告字体、卡通字体、夸张手写体或装饰字体。
+    
+
+标题颜色从照片或抽象母题中选择一种较深、较克制的主体色，例如深蓝灰、暗绿、酒红、深紫或炭灰。必须保证在面板背景上清晰可读，但不要默认使用纯黑。
+
+副标题使用同色系、更浅或更低饱和度的颜色。
+
+标题颜色应与照片主体建立联系，不得使用最鲜艳的强调色抢夺视觉中心。
+
+## 十、CLEAN 模式
+
+抽象面板背景不得出现：
+
+渐变、光照变化、阴影、发光、暗角、色带、接缝、纸张纹理、颗粒、噪点、纤维、水彩底纹、雾、污渍、褪色、灰蒙、扫描痕迹、贴图或压缩伪影。
+
+抽象标记可以具有轻微自然边缘和手工不规则感，但不得依靠材质噪点制造气氛。
+
+气氛只能来自：
+
+留白、距离、停顿、非对称、尺度差、有限标记和克制配色。
+
+## 十一、输出限制
+
+只输出一张完成的摄影与抽象面板拼接作品。
+
+除最终确定的主标题和可选副标题外，绝对不要出现任何文字、数字、日期、编号、地点说明、色卡、图例、签名、logo 或水印。
+
+严格避免：
+
+照片重画、场景重建、生成式扩图、滤镜感、海报化照片、矢量化描摹、完整插画、规则化信息图、通用图标、密集装饰、虚构内容、虚构对称、非均匀背景、写实小物件、过度建筑细节、整齐胶囊形人影、标题候选列表和额外文字。

package/.agents/skills/trip-moments/references/ai-apis.md

@@ -0,0 +1,153 @@
+# AI 图像接口速查(自建网关 / 硅基流动 / 智谱 BigModel / 阿里云百炼)
+
+脚本已封装好(`aiclient.py`),本文供排错和调参用。所有请求均为 JSON over HTTPS。
+
+## 自建网关(TRIP_AI_BASE_URL + TRIP_AI_API_KEY,2026-09 实测)
+
+按模型名自动路由,aiclient 已封装;手写请求时注意三者协议不同:
+
+- **视觉 / gemini-3.x-flash**:标准 `POST /chat/completions`,图放 `image_url`
+  data URL。gemini 回 JSON 常包 ```json 围栏,GLM 系会夹带 `<|begin_of_box|>`
+  标记,解析前都要清洗(`aiclient.json_from_reply` 已处理)。
+- **gpt-image 系列**:原生 OpenAI 协议。编辑 = `POST /images/edits`
+  **multipart 表单**(image 文件 + prompt + model,尺寸参数叫 `size`);
+  文生图 = `POST /images/generations` JSON + `size`。响应固定 `data[].b64_json`。
+- **gemini-3.1-flash-image(nano-banana 族)**:**只支持 chat 协议**,图进图出——
+  输入为 image_url 消息,生成图在 `choices[0].message.images[].image_url.url`
+  (data URI,content 为 null)。`/v1/images/*` 会直接被网关拒绝。
+- 常见错误:`429 credentials cooling down`(账号池限速,稍后重试)、
+  `auth_unavailable`(账号池无凭据,需网关侧刷新授权)、
+  `403 Forbidden`(key 无该模型权限)。
+
+## 硅基流动 SiliconFlow(base: https://api.siliconflow.cn/v1,OpenAI 兼容)
+
+鉴权:`Authorization: Bearer <SILICONFLOW_API_KEY>`(或任意兼容网关:OPENAI_BASE_URL + OPENAI_API_KEY)
+
+### 视觉理解(select9.py 的 AI 打分)
+
+```
+POST /chat/completions
+{
+  "model": "zai-org/GLM-4.5V",                    // TRIP_VL_MODEL 可覆盖;旧型号会下架
+  "messages": [{
+    "role": "user",
+    "content": [
+      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}},
+      {"type": "text", "text": "<评分指令,要求只输出 JSON>"}
+    ]
+  }],
+  "temperature": 0.2
+}
+```
+响应:`choices[0].message.content`(标准 OpenAI 格式)。
+模型在 <https://siliconflow.cn/models> 挑,免费档小视觉模型也够用。
+
+### 图像生成/编辑(统一 /images/generations,编辑=带 image 参数)
+
+```
+POST /images/generations
+{
+  "model": "Qwen/Qwen-Image-Edit",                // TRIP_EDIT_MODEL 可覆盖
+  "prompt": "去掉画面中的游客,保持背景自然",
+  "image": "data:image/jpeg;base64,..."           // 编辑必填;文生图省略
+}
+```
+- 文生图模型:`Kwai-Kolors/Kolors`(TRIP_T2I_MODEL)、`Qwen/Qwen-Image`、`black-forest-labs/FLUX.1-schnell` 等
+- 编辑模型:`Qwen/Qwen-Image-Edit-2509`(默认,人物一致性更好)或 `Qwen/Qwen-Image-Edit`(旧版);
+  编辑是"看图重绘",指令遵循好,但细节可能被重渲染,对"只调色不动内容"的诉求要提醒用户
+- 可选参数:`image_size: "1024x1024"`(宽高拼一起)、`negative_prompt`、`seed`、`batch_size`(1-4)
+- 响应:**`{"images": [{"url": "..."}], "timings": {...}, "seed": ...}`** —— 是 `images` 数组
+  不是 OpenAI 的 `data`;URL **仅 1 小时有效**,脚本会立即下载转存
+- 客户端同时兼容返回 `data[].url` / `data[].b64_json` 的其他兼容网关
+
+常见错误:`401 Invalid token`=key 错;`403 Model disabled`=模型已下架(换 TRIP_*_MODEL);
+`429`=限流;`503 code 50505`=模型过载(重试);
+`400 code 20012`=参数错(检查 image 是否为 data URL、模型名是否拼写正确)。
+
+## 智谱 BigModel(base: https://open.bigmodel.cn/api/paas/v4)
+
+鉴权:`Authorization: Bearer <ZHIPU_API_KEY>`
+
+### 视觉理解(select9.py 的 AI 打分;glm-4v-flash 免费)
+
+```
+POST /chat/completions
+{
+  "model": "glm-4v-flash",
+  "messages": [{
+    "role": "user",
+    "content": [
+      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}},
+      {"type": "text", "text": "<评分指令,要求只输出 JSON>"}
+    ]
+  }],
+  "temperature": 0.2
+}
+```
+响应:`choices[0].message.content`。一次消息里放多张 `image_url`(当前脚本每批 5 张)。
+其他可用:`glm-4v-plus`(更强,收费)。
+
+### 文生图(poster.py panel 模式的抽象画板)
+
+```
+POST /images/generations
+{"model": "glm-image", "prompt": "<≤1000字>", "size": "1728x960"}
+```
+- size 推荐:1280x1280 / 1056x1568 / 1568x1056 / 1728x960 / 960x1728;自定义需 1024–2048 且为 32 的倍数
+- 响应:`data[0].url`(30 天有效,及时转存);`cogview-3-flash` 免费档可替代
+- **没有图像输入参数**——智谱不能"看着照片改照片",修图请用硅基流动或百炼
+
+错误格式:`{"error": {"code": "...", "message": "..."}}`;401=key 错,429=限流/欠费。
+
+## 阿里云百炼(base: https://dashscope.aliyuncs.com/api/v1)
+
+鉴权:`Authorization: Bearer <DASHSCOPE_API_KEY>`;图像编辑为**异步任务**两步式。
+
+### 第 1 步:提交任务
+
+```
+POST /services/aigc/image2image/image-synthesis
+Headers: X-DashScope-Async: enable
+{
+  "model": "wanx2.1-imageedit",
+  "input": {
+    "function": "description_edit",
+    "prompt": "去掉画面中的路人",
+    "base_image_url": "data:image/jpeg;base64,..."
+  },
+  "parameters": {}
+}
+```
+响应:`{"output": {"task_id": "...", "task_status": "PENDING"}, "request_id": "..."}`
+
+### 第 2 步:轮询(2-3 秒一次,通常 10-40 秒出图)
+
+```
+GET /tasks/<task_id>
+```
+- `output.task_status`:`PENDING` → `RUNNING` → `SUCCEEDED` / `FAILED`
+- 成功后取图:`output.image_url`(部分 function 返回 `output.results[].url`)
+
+### function 取值(retouch.py 已映射)
+
+| retouch.py 参数 | function | 用途 |
+|---|---|---|
+| `-f edit` | `description_edit` | 指令编辑:去路人/换天/调色(默认) |
+| `-f erase` | `erase_anything` | 擦除指定元素 |
+| `-f expand` | `expansion` | 扩图(改变画幅) |
+| `-f style` | `style_repaint` | 风格化(胶片/动漫等) |
+| `-f colorize` | `colorization` | 老照片上色 |
+| `-f upscale` | `image_ultra_quality` | 画质提升/超分 |
+
+> function 名称以官方文档为准:<https://help.aliyun.com/zh/model-studio/wanx-image-edit-api-reference>
+> 若返回 `InvalidParameter`,优先怀疑 function 名或 `base_image_url` 格式。
+> 备选模型:`qwen-image-edit`(多模态消息式接口,指令跟随更细)。
+
+### 常见错误
+
+| 现象 | 原因 |
+|---|---|
+| HTTP 401 | key 无效或没开通百炼 |
+| `InvalidApiKey` | key 和区域不匹配(北京区域用默认域名) |
+| 任务 FAILED + `InvalidParameter.*url` | base_image_url 不被接受:改用公网 URL(如先传 OSS) |
+| 出图上有二维码水印 | `watermark_enabled`/`parameters.watermark` 相关参数未关 |