ppt-master 网络图片采集链路全解析image-searcher 角色规范与 image_search.py 实战指南【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master本指南以 ppt-master 的Image_Searcher角色参考手册image-searcher.md为核心骨架系统讲解通过开放许可图片提供商获取合规网络图片的完整链路从许可层级纪律、查询翻译、提供商链到image_search.py的单一查询、批处理、缩略图可视化选择与image_sources.json溯源清单并结合仓库源码image_search.py、provider_common.py、image.md与回归测试test_image_search.py给出实现级证据。读完你能够独立执行一条意图 → 查询 → 许可筛选 → 下载 → 溯源落盘 → 署名渲染的合规网络取图流水线并理解每个配置项背后的代码语义。1. 角色定位与触发条件Image_Searcher是 ppt-master 两条图片获取路径AI 生成 vs 网络搜索中网络获取路径的专职角色与 AI 生成路径的Image_Generator平行。其职责边界非常明确把资源所有者的意图Reference翻译成关键词查询在开放许可提供商中搜索下载一张许可合规的图片到project/images/并在image_sources.json中记录溯源provenance与许可信息。触发条件有两种Default 流程的资源清单中存在Acquire Via: web的行Quick 流程在活跃上下文中解析出一个必需的 web 图片。角色触发后读取公共基线文档 image-base.md共享框架与 shared-standards-core.mdSVG/PPT 技术约束。其中 image-base.md 明确给出路径分发矩阵web行由本角色执行image_search.py有视觉能力时走有界的缩略图页 选定一张原图无视觉能力时走严格元数据排序的最优单张成功状态为SourcedNeeds-Selection只是中间态。2. 许可层级纪律License Tier Discipline所有提供商来源的图片只允许落进两个许可层级之一其余一律拒绝manual层级仅存在于两种场景用户直接选定 URL 替换--from-url或采纳页面adopted-page的打包图片——绝不用于许可未知的提供商结果。下游消费者只读license_tier字段绝不自行解读原始许可字符串。层级许可范围幻灯片内署名no-attributionCC0、Public Domain、Pexels License、Pixabay Content License无attribution-requiredCC BY、CC BY-SA幻灯片内联署名textmanual直接选定的 URL 或采纳页面图片许可未验证无——权利与署名责任由用户承担自动拒绝清单CC BY-NC、CC BY-NC-SA、CC BY-ND、CC BY-NC-ND、All Rights Reserved、未知或缺失许可。这套分层在源码中被实现为classify_license()provider_common.py中的三组令牌判定NO_ATTRIBUTION_TOKENS含cc0、public domain、pexels license等命中则归为no-attributionATTRIBUTION_REQUIRED_TOKENS含cc by、cc-by、by-sa、creativecommons 链接命中则归为attribution-requiredREJECTED_TOKENS含by-nc、noncommercial、by-nd、no derivatives、all rights reserved命中直接返回None拒绝。同时为 Pexels/Pixabay 提供 Provider 兜底当许可文本中出现提供商名且不含 CC BY 类令牌时按站方免费商用、免署名政策归入no-attribution且空许可字段永远不会静默通过。3. 搜索策略质量优先 两种工作模式核心原则是质量优先于许可便利——绝不为了一张 CC0 图而放弃一张更好的 CC BY 图因为清单里的license_tier让 Executor 只在必要时补署名。--strict-no-attribution仅 CC0 / PD / Pexels / Pixabay是显式开启的选项只用于无法承载任何幻灯片内署名的 deck。Multimodal Generate: explicit query variants × provider chain allowed licenses → aggregate/deduplicate/rank → first 8 thumbnails → visually select → download one original; if none passes, inspect the next 8 first. Non-visual / standalone best-only: explicit query variants × provider chain → strict metadata gate → first downloadable ranked original wins.从源码看两种模式共用search_and_download()image_search.py许可阶段循环all或no-attribution-only× 提供商循环 × 查询变体循环层层聚合后去重排序区别仅在save_candidates开关——为真时只落缩略图候选页并返回selection_required为假时按排序逐个尝试下载可下载的最佳候选。4. 提供商链Providers提供商配置优势PexelsPEXELS_API_KEY免费官方 API 注册现代商业图库摄影人物、职场、生活方式PixabayPIXABAY_API_KEY免费覆盖面广含插画其 API 长边最多 1280px全出血 hero 优先用 Wikimedia 或 PexelsOpenverse零配置兜底聚合器Wikimedia Flickr 博物馆 rawpixelWikimedia Commons零配置教育、科学、地理、历史素材壁画、手稿、艺术品、博物馆物件应provider: wikimedia固定提供商商业图库会把这些标签成游客照默认链路为pexels→pixabay各在配置了 key 时启用→openverse→wikimedia配置了 key 但没有 key 的提供商被静默跳过。当图库覆盖符合需求时才配置 Pexels 或 Pixabay缺 key 绝不是失败。代码证据PROVIDER_MODULES注册表与ZERO_CONFIG_PROVIDERS/KEYED_PROVIDERS常量在 image_search.py默认链路由_default_provider_chain()image_search.py动态构造——先检查PEXELS_API_KEY/PIXABAY_API_KEY环境变量有则前置随后永远追加两个零配置提供商。key 缺失的处理在_is_keyed_provider_unconfigured()image_search.py把缺 key当作非致命跳过让默认链路继续。配置文件查找顺序与image_gen.py相同进程环境 当前目录.env 技能目录 克隆根 ~/.ppt-master/.env详见 image.md。5. 意图 → 查询翻译Intent → Query Translation这是本角色最关键的翻译能力涉及两层所有者层所有者与语法Defaultdesign_spec.md §VIII Reference/ Quick 活跃上下文的Reference资源所有者完整的视觉意图——精确主体、视角/氛围、焦点或安静区域、裁剪安全、正向质量提示——整次运行锁定本角色绝不重写image_queries.json.items[].query/ 位置参数查询本角色产出的具体实体关键词字符串保留身份的最短短语即使超过四个词也要保留完整专名与消歧词不含情绪、质量、构图、HEX 或否定词关键认知Web API 匹配的是元数据不是意图。因此提供商会对每个显式查询依次尝试逐级简化的四/三/二/一词变体build_query_progression()在 provider_common.py 中实现先剥离 HEX 色值与括号旁注再删除品牌名等硬噪声词、仅在保留实词的前提下删除软噪声词最终封顶在max_words个词。所以主query应保持简洁把官方翻译、拼写、别名、中文名等实质性不同的写法放进query_variants绝不能只做无意义的词序变换中国地标场景下把 Wikimedia 中文名与紧凑英文身份词配对使用。一个候选要么满足既有意图要么角色尝试实质性不同的查询/提供商/许可策略直到穷尽然后标记Needs-Manual绝不允许为了凑出一个匹配而放宽required_terms、许可策略或意图。required_terms精确实体的硬性身份闸门对于地标、人物、公司、产品、场馆、具名艺术品与机构必须随查询写入required_terms——每个身份锚点一组|表示别名例如[Chongqing|重庆, Jiefangbei|解放碑|Liberation Monument]。绝不放宽成类别词canyon、stone pillar、ancient town、bridge、temple——这些词属于查询本体元数据无法证明的小众/本地景点最终走向Needs-Manual或用户--from-url而不是一张看起来像的错地点的图片。同时required_terms不得用于通用氛围行如 modern city skyline、team collaboration。禁止否定词如not tourist snapshot、no amateur photo关键词 API 会按字面搜索它们。required_terms的判定逻辑是实体安全闸门不是模糊视觉分类器missing_required_terms()provider_common.py把每个分组按|拆成别名做规范化后的子串匹配任一别名命中即算该组通过。源码还内置了弱词告警_WEAK_REQUIRED_TERM_PARTSimage_search.py收录了 36 个中英文类别词canyon、stone pillar、temple、峡谷、石柱、地缝、寺等_warn_weak_required_terms()image_search.py会在这些词出现在身份闸门中时向 stderr 打出警告提示保留专名/地理锚点并优先Needs-Manual或--from-url而非放宽身份闸门。§VIII Reference意图→ 提供商查询示例§VIII Reference意图Provider queryOffshore wind farm at dusk, aerial view, quiet sky on the left for safe cropoffshore wind farmDiverse engineering team around a laptop, modern office, natural lightengineering team laptopChongqing Jiefangbei monument, full structure visible, landscape frameChongqing Jiefangbei monument6. 运行 image_search.py6.1 单查询模式python3 scripts/image_search.py query --filename name.jpg --slide slide_id \ --orientation landscape --purpose background -o project_path/images典型示例取自脚本 docstring 与 image.mdpython3 scripts/image_search.py offshore wind farm \ --filename cover_bg.jpg --slide 01_cover \ --orientation landscape -o projects/demo/images6.2 参数总表参数默认值说明query位置参数必填—内部会做简化处理--query-variant—可重复的别名/翻译批处理行用query_variants--filename必填—与资源清单一致的目标文件名-o / --output.输出目录清单默认落在output/image_sources.json--slide、--purpose、--orientation、、any记录的幻灯片 idbackground/hero/side/accentlandscape/portrait/square--min-width / --min-height1200 / 800下载像素下限--from-url尊重显式的更低覆盖值--provider默认链路固定单个提供商--strict-no-attribution关拒绝 CC BY / CC BY-SA--require-terms—可重复的身份闸门逗号分隔组A|B表示别名--save-candidates关缩略图模式保存一页排序预览 review_sheet.jpg不下载原图--max-candidates8每页大小0 全量候选仅调试用--candidate-page1排序页第 2 页从第 9 名开始。单查询延续继承已保存的池请求批处理则在指定页重跑所有Needs-Selection行--promote candidate—精确下载所选的一张原图执行闸门校验写入溯源--from-url url—手动替换记录为license_tier: manual无视觉能力也可用--manifest pathimages/image_queries.json覆盖清单路径关于--require-terms的 CLI 语法可重复传入逗号分隔组、A|B表示组内别名例如--require-terms Chongqing --require-terms Jiefangbei|Liberation Monument_parse_required_terms()见 image_search.py。值得注意的 CLI 约束见build_parser()与main()的校验image_search.py--max-candidates 0时--candidate-page必须为 1批处理模式下禁止出现位置参数 query除非配合--promote或--from-url--candidate-page N延续候选池时必须保持池的原 query改 query 等于开启新的第 1 页。6.3 批处理模式≥2 个 web 行时优先把每一行写进image_queries.json一次并发批跑这是image_gen.py --manifest的 web 姊妹模式只要 Agent 能看图就加上--save-candidatespython3 scripts/image_search.py --batch project_path/images/image_queries.json -o project_path/images --save-candidates{ items: [ { filename: jiefangbei.jpg, query: Jiefangbei Chongqing downtown monument, query_variants: [Chongqing Liberation Monument, 重庆 解放碑], slide: 03_landmark, purpose: exact landmark photo, orientation: landscape, required_terms: [Chongqing, Jiefangbei|Liberation Monument], status: Pending } ] }每行必填filename、query、status可选query_variants、candidate_page、slide、purpose、orientation、provider、strict_no_attribution、min_width、min_height、required_terms。批处理运行器的行为image_search.py重校验Sourced行核对image_sources.json有无匹配溯源、目标文件是否存在、实际尺寸是否达标漂移则打回Failed并在下次重试并发搜索所有Pending/Failed行默认并发 3DEFAULT_SEARCH_CONCURRENCYimage_search.py可用--concurrency N或IMAGE_SEARCH_CONCURRENCE环境变量调整对限速敏感的免费提供商建议1做严格串行。注意免费提供商讲究访问礼貌Wikimedia/Openverse 期待适中速率所以默认并发刻意低于付费 API 的image_gen.py缩略图模式下把行写成Needs-Selection并携带分页字段candidate_page、candidate_count、candidate_total、has_more_candidates、next_candidate_page、review_sheet不产生任何图片或溯源每完成一行即原子写回状态中断安全已完成的行保持Sourced。排序ranking只基于提供商元数据绝不基于像素且不允许被调教成审美引擎score_candidate()与score_review_candidate()见 provider_common.py硬拒绝无效许可与零相关度best-only 模式拒绝任何缺少required_terms组的候选缩略图模式严格匹配排前、仅当恰好缺一组且命中查询仍有强相关时才放行近似匹配标记identity_evidence: visual-verification-required绝不自动 promote标题中出现元数据可验证的身份优于仅 URL 命中查询词按完整 ASCII 词元匹配office≠officer且优先于通用词方向是小罚分、免署名是小加分、像素数有上限——巨型弱匹配无法击败更小的精确匹配。7. 适用性评审缩略图可视化选择 vs 纯元数据模式核心警告命中的图片可下载且词面相关≠视觉合适。评审者只收到锁定的行意图外加候选 sidecar/拼版图绝无完整规划或获取上下文。7.1 有视觉能力vision加上--save-candidates工具只保存排序后第一页默认 8 张的可评审提供商预览到candidates/stem/review/并生成拼版图review_sheet.jpg目标图片与清单保持不动直到 promote。随后运行 web-image-review.md 中定义的隔离评审——整个批次优先派一个隔离评审者否则本地评审——然后只有图片所有者能 promote 返回的文件名。评审契约web-image-review.md按序通过五道闸门① 仅接受license_tier为no-attribution或attribution-required拒绝不可读预览或已知尺寸无法服务版式的候选② 确认精确主体/身份visual-verification-required仅在像素确凿补齐缺失证据时通过③ 对照锁定意图检查方向、焦点位置、裁剪安全与可用安静区域④ 检查所需视角、动作与氛围⑤ 通过者中优先裁剪损失更小、可用分辨率更高的其次免署名。评审还强制有界细节检查先用拼版图粗筛只有无法从拼版图确认精确身份或细节时才逐张打开review/candidate_NN.jpg绝不批量全开。绝不 promote最不坏的候选。如果无一通过且has_more_candidates为真先取--candidate-page 2再考虑改查询。对精确实体required_terms只是元数据闸门评审图片必须确认像素确实呈现主体并满足焦点/裁剪意图——一个笼统的required_terms通过不是验收比如匹配 Ground Fissure 可能返回一个名叫 Yunlong 的无关节点。# 独立缩略图选择Generate 之外可选开启 python3 scripts/image_search.py query --filename name.jpg -o project_path/images --save-candidates python3 scripts/image_search.py --promote candidate_03.jpg --filename name.jpg -o project_path/images python3 scripts/image_search.py same query --filename name.jpg -o project_path/images --save-candidates --candidate-page 2 python3 scripts/image_search.py --promote candidate_03.jpg --filename name.jpg --batch project_path/images/image_queries.json -o project_path/images预览落在images/candidates/stem/review/附带仅含缩略图的candidates.json页号、大小、总数、has_more_candidates、命中查询、身份证据与当前轮次的review_sheet.jpgpromote 之前目标与清单保持不动。promote_candidate()的实现image_search.py把下载 校验 换入目标 写溯源 推进 candidates.json作为一个可回滚的提交单元下载的原图必须先通过尺寸/可读性闸门才连同溯源一起_commit_staged_image()image_search.py落盘任何一步失败都会回滚旧文件。候选页的延续由_retained_pool_candidates()保证只要目标文件名与 query 不变早前页面的缩略图会保留在candidates.jsonsaved_pages任何已保存缩略图都可随时 promote。回归测试 test_image_search.py 专门验证了这一行为。7.2 无视觉能力省略--save-candidates工具排除近似匹配只下载第一个通过全部严格元数据/许可/尺寸闸门的候选并记录selection_method: metadata-ranked——绝不能描述为视觉确认。如果没有严格候选或意图需要视角、裁剪、表情或精细身份而元数据无法确立就标记Needs-ManualQuick 流程不开启任何交互。7.3 替换阶梯Replacement Ladder有视觉能力promote 那张通过的缩略图has_more_candidates为真取下一页编号全局连续第 2 页从candidate_09开始池耗尽后追加实质性不同的身份/翻译/别名/视角/消歧变体重新生成新池仅在有视觉能力时常规搜索耗尽后按 topic-research.md 的 Hand-off 章节取一个采纳的source_url作为 Markdown 配套图片包复制一张通过图片到images/并依据其image_manifest.json条目把行与image_sources.json对账为license_tier: manual绝不自动扩展事实 URL也绝不 promote 整个包手动 URL 替换——python3 scripts/image_search.py --from-url image-url --filename name.jpg -o project_path/images——记录为manual仅当 Quick 中已提供 URL 时才允许它会更新图片与image_sources.json但不会更新image_queries.json所以导出前需校验文件并把查询行与名单对账为Sourced见 executor-web-image.md当变体、页面、提供商、许可阶段与包回退全部耗尽标记Needs-Manual。这条评审链在整个获取过程中不开启任何获取时交互image-base.mdDefault 可用占位符继续到 Step 6Quick 在图片为必需时阻止直接导出。8. 溯源清单image_sources.json每次成功下载都会按filename为键追加或替换一条记录原子写入、幂等不可读的既有清单会阻塞写入。license_tier驱动 Executor 的署名决策attribution_text是规范署名来源width/height以实际保存文件实测为准selection_method记录visual-thumbnail评审后 promote或metadata-ranked严格路径。{ license_verification: provider metadata used; manual review recommended for external delivery, generated_at: 2026-05-01T12:17:59.856275Z, items: [ { filename: team.jpg, slide: 03_team, purpose: Leadership photo, search_query: executive boardroom meeting, matched_query: leadership team boardroom, selection_method: metadata-ranked, orientation: landscape, provider: openverse, stage: all, title: Untitled, author: , source_page_url: https://www.rawpixel.com/..., download_url: https://..., license_name: CC0, license_url: https://creativecommons.org/publicdomain/zero/1.0/, license_tier: no-attribution, attribution_required: false, width: 1024, height: 683, metadata_dimensions: { width: 4800, height: 3200, note: upstream-reported size; actual downloaded file is smaller (likely a preview) }, attribution_text: team.jpg — \Untitled\ via Openverse — license: CC0 (...), status: sourced } ] }字段语义完整说明见 image.mdmatched_query实际命中该素材的查询或变体selection_method评审 promote 后为visual-thumbnail严格路径为metadata-rankedwidth/height从保存的文件实测用于布局当上游声称的尺寸与实测不一致时才出现metadata_dimensionslicense_tier驱动 Executor 署名的唯一依据attribution_text规范署名来源只能按第 9 节的语法压缩stageall或no-attribution-only。实现上width/height来自下载后的 Pillow 实测_measure_actual_image()image_search.py而非上游元数据——因为 Openverse 聚合的 rawpixel 等二级源常只暴露预览图metadata_dimensions仅在两者不一致时携带并在单查询模式下于 stderr 给出下载图远小于上游声明的警告image_search.py。此外下载物还会经_validate_downloaded_quality()image_search.py做双重校验请求的min_width/min_height下限 绝对像素地板_MIN_DOWNLOAD_PIXELS 800 × 600相机多画面 JPEGMPOCommons 原件常见会在校验前被_normalize_multi_frame_jpeg()image_search.py重写为主帧保证后续image_treat.py、质量检查器与 PPTX 导出器看到的都是单帧 JPEG——对应回归测试 test_image_search.py。清单的写入走_write_json_atomic()image_search.py同目录临时文件 原子 rename失败自动清理临时文件。write_sources_manifest()image_search.py还校验文件名合法性裸文件名、无路径成分、大小写不敏感冲突检测损坏的既有溯源会阻断覆盖。9. 幻灯片内署名契约On-Slide Attribution Contract对license_tier: attribution-required的素材使用该素材的每一页都必须有一条可见、可读、与该素材唯一绑定的署名完整保留attribution_text中的作者、来源/提供商与 CC BY / CC BY-SA 事实。位置、字号、颜色、逐图署名还是合并署名、标签与对比度处理都属于页面职责单图图片边缘或脚注区放紧凑署名多图逐图署名或一条带标签的合并行Hero仅在对比度不足时用安静区scrim 或渐变。压缩时不得丢失必需事实语法示例team.jpg — Untitled via Openverse — license: CC0 (...)→via Openverse / CC0team.jpg — Sunset by Jane Doe via Wikimedia Commons — license: CC BY-SA 4.0 (...)→© Jane Doe / Wikimedia / CC BY-SA 4.0署名渲染发生在 Executor 侧executor-web-image.md按license_tier分派——no-attribution与manual只嵌imageattribution-required加第 7 节的内联署名署名写入你编排的 SVG 中绝不靠后处理或导出。质量校验闭环svg_quality_checker.py会验证每个被引用的 attribution-required 图片都有自己可见的作者 许可署名——一个 deck 级 CC 令牌绝不能覆盖多张图同时会报错不可读清单或缺失按文件溯源。署名数据只存在于project/images/image_sources.json绝不进入notes/*.mdTTS 会读、total.md或 SVGtitle/desc导出时会被剥离收尾的 sources 页可以汇总但不能替代逐页署名。10. 失败处理web 特有在 image-base.md §3 的硬规则之上扩展穷尽一切被允许的策略之前绝不阻塞——网络、无候选、许可拒绝、限速等可恢复失败要沿路径权限内实质性不同的策略继续且不重复已穷尽的策略。具体失败语义详见 image.md 与第 7 节替换阶梯候选与变体全部穷尽 →Needs-Manual附原因提供商或网络失败 → 保持可重试的Failed批处理会稍后重跑promote 的原图未通过闸门 → 保持Needs-Selection换一张或改查询某页预览部分失败而另一张合格 → 保留合格集全部预览失败或提供商/网络失败 →Failed由后续批次重试best-only 下载 403/404 → 分发器自动落到下一个排序候选有 key 的提供商缺 key → 跳过见第 4 节。退出码语义准备好的Needs-Selection集返回0Failed或Needs-Manual返回1。批处理运行器run_search_manifest()会把三类结果分别统计并逐行写回状态image_search.py[OK]/[REVIEW]/[FAIL]/[MANUAL]中断KeyboardInterrupt返回 130 且已完成的进度保留在清单中。11. 与上游意图所有者和下游 Executor 的交接与意图所有者Strategist / Quick 主 AgentReference是意图不是查询image-base.md。保持其作为验收契约原封不动从中派生一条独立的、保留精确名称与消歧的简洁提供商查询搜索后绝不原样传递或重写意图。与 ExecutorExecutor 按幻灯片读取image_sources.json只依据license_tier行动——no-attribution和manual只嵌imageattribution-required追加第 9 节署名——不解读许可字符串。svg_quality_checker.py负责验证每张被引用图片都有自己可见的作者 许可署名详见第 9 节。Default Executor 从不调用image_gen.py/image_search.py/slice_images.py/image_treat.py——缺素材时返回 Strategist 所有的准备阶段Quick 在写图前完成获取与派生绘制时既不获取也不重选。12. 任务完成检查点Task Completion Checkpoint在 image-base.md §4 的公共检查点之上web 路径追加以下验收项每个必需 web 行均为Sourced且原图位于project/images/filename或为带原因的Needs-ManualNeeds-Selection视为未完成每张多模态Sourced图片来自一个有界的缩略图页且只有赢家被下载剩余页面在改查询前已穷尽无视觉能力时只有严格元数据候选成为Sourced且selection_method: metadata-ranked每个Sourced行都有合法的license_tier与非空attribution_textmanual除外每张 attribution-required 图片在引用它的每个 SVG 中都有署名下载尺寸远小于声明时metadata_dimensions警告已被暴露处理。收尾后Default 流程可带着已验证的图片素材进入 ExecutorQuick 只在证据与状态均验证通过时才导出。整套链路的设计边界image.md可以概括为一句话提供商凭据显式化、管道内获取清单驱动、外部图片引用视为编排输入而交付产出自包含的 SVG 预览与原生 PPTX 媒体——image_search.py与image_sources.json正是这条边界上最核心的两个落点。【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考