UI 灵感库

将 UI 参考素材以结构化方式归档至灵感库中，待实际需要时再精准检索出最匹配的参考项。

本能力包含三项核心承诺：

1. 干净地保存图像，使其可复用于灵感库；
2. 支持高效检索，通过适配检索场景的元数据增强可发现性；
3. 搜索时返回匹配的原始图像本身，而非仅返回文字摘要。

请将该库视为一个持续运转的视觉搜索系统，而非静态存档。检索质量与入库质量同等重要。

核心能力

1. 归档模式（Archive mode）

当用户希望执行以下操作时启用：

• 保存 UI 截图；
• 收集设计灵感；
• 归档设计参考；
• 为图像打标签以便后续复用；
• 构建团队或个人 UI 灵感库。

目标：

• 对输入图像进行标准化处理；
• 将其分析为可复用的设计参考；
• 生成适配检索需求的元数据；
• 将元数据与原始图像一并存入目标库。

返回内容应包括：

• 简洁标题；
• 关键标签；
• 归档结果状态；
• 必要时提供条目链接。

2. 检索模式（Retrieval mode）

当用户希望执行以下操作时启用：

• 搜索灵感库；
• 为特定设计目标浏览参考素材；
• 对比不同视觉方向；
• 按关键词、风格、页面类型或使用场景查找参考；
• 直接获取匹配的原始图像。

目标：

• 准确理解用户的视觉/设计意图；
• 向后端库发起查询；
• 对强匹配结果进行排序；
• 尽可能返回原始图像本身；
• 为每个匹配项简要说明其契合原因。

若用户明显处于参考浏览阶段，请优先采用以图像为先的响应形式，而非纯文本报告。

模式选择规则

根据用户输入选择对应工作流：

• 若用户提供一张或多张截图，或明确要求保存/归档/打标签，则启用 归档模式；
• 若用户请求参考、示例、灵感、对比或相似视觉素材，则启用 检索模式；
• 若用户既提供截图又要求对比、筛选或查找相关参考，请视需先执行归档，再运行检索或对比流程；
• 若用户意图不明确，请提出一个简短澄清问题，切勿自行猜测。

后端配置发现机制

假设后端标识符及访问细节来源于运行时配置、环境变量、用户提供的参数，或现有项目文档。

向后端写入前需完成以下判断：

• 确定应使用哪个后端；
• 确认归档与检索是否共用同一后端；
• 确定如何定位目标数据库或集合；
• 在启动完整归档流程前，验证读写权限。

若目标后端未指定或不可自动发现，则：

• 写入前向用户提出一个简短问题；
• 明确询问目标库应存放于何处；
• 主动询问用户是否需要协助创建新库（若当前不存在）；
• 不得猜测私有数据库标识符；
• 除非父级位置已知且运行时明确被允许创建，否则不得自动新建库；
• 即使无持久化能力，仍应提供图像分析与结构化元数据输出。

默认工作流

归档工作流

1. 识别来源渠道，并在本地获取图像；
2. 将输入标准化为稳定图像源或文件；
3. 将图像作为 UI 灵感参考进行分析；
4. 生成面向未来检索优化的结构化元数据；
5. 创建目标库记录；
6. 将原始图像上传或附加至该记录；
7. 返回简短归档确认信息。

检索工作流

1. 解析用户意图；
2. 映射至一个或多个检索维度：
   • 视觉目标；
   • 页面类型；
   • 风格标签；
   • 组件标签；
   • 使用场景；
   • 摘要/高亮/来源中的关键词信号。
3. 查询库；
4. 依据真实设计实用性对结果排序；
5. 返回 1–5 个高质量匹配项，多数情况下优选返回 3 个；
6. 尽可能发送原始图像；
7. 为每项结果附加 1–2 行理由说明。

以检索为先的规则

当用户表达如下语义时：

• “给我一些参考”
• “找些类似示例”
• “哪些适用于封面？”
• “找 AI 风格的首屏参考”
• “选几个仪表盘参考”

默认其需求是可直接使用的视觉参考，而不仅是文字描述。

推荐的检索输出顺序为：

1. 图像预览；
2. 简短标题；
3. 匹配理由；
4. 可选条目链接。

少量高质量匹配远优于大量低质匹配。

多图、重复与更新规则

除非用户另有说明，否则采用以下默认行为：

• 每张图像单独创建一条记录；
• 每张图像独立分析；
• 仅当用户明确要求“成组参考集”时，才将多张图像合并为一条记录；
• 仅当用户明确指向某条已有记录时，才更新该记录；
• 向已有记录添加图像时，默认追加而非覆盖；
• 仅当用户明确使用“替换”或“覆盖”等措辞时，才替换原有图像。

对可能的重复项采取保守处理策略：

• 若检测到相同图像已被归档，优先发出警告或征询用户意见，而非创建近似重复记录；
• 若标题重复但图像内容存在实质性差异，应新建记录，而非静默合并；
• 若重复检测能力较弱或结果不确定，应保留新条目并明确声明不确定性。

分类规则

以提升未来检索效率为首要目标，而非追求穷尽式批判分析。

除非存储后端不支持，否则应使用以下最小元数据集：

• 标题；
• 摘要；
• 页面类型；
• 风格标签；
• 组件标签；
• 使用场景标签；
• 原始图像或来源链接。

应用以下约束条件：

• 标题须简短、具体、利于检索；
• 优先选用稳定可复用的标签，避免临时性、创意性措辞；
• 页面类型限用 1–3 种；
• 风格标签限用 2–5 个；
• 组件标签限用 2–6 个；
• 使用场景标签限用 1–3 个；
• 在有助于理解时，以用户语言撰写 2–5 条简短高亮；
• 以用户语言撰写一段聚焦参考价值的简洁摘要；
• 若存在不确定性，应选择更宽泛的类别，而非虚构精确分类。

来源与隐私规则

谨慎使用 source 字段。

推荐的来源优先级顺序为：

1. 用户提供的公开来源 URL；
2. 可安全推导出的规范页面 URL；
3. 渠道或来源标签，例如 telegram upload 或 manual upload；
4. 用户自定义的来源备注。

除非用户明确要求，否则禁止在长期记录中存储私有本地文件系统路径、临时下载 URL、访问令牌或账号专属传输细节。

归档前需识别低价值或敏感图像：

• 不可读、严重裁剪或分辨率极低的截图；
• 以个人数据为主导的截图；
• 含私有内部仪表盘、客户数据或密钥的截图；
• 参考价值过弱、不足以支撑存储的图像。

默认行为：

• 对明显敏感的截图，在存储前发出警告；
• 默认不归档敏感的内部或个人截图，除非用户明确确认其愿意存储；
• 当用户意图不清晰时，对低价值或模糊材料归档前需征询用户意见；
• 若用户仍坚持归档，可继续执行，但须简洁记录其局限性。

输出要求

最小归档输出

至少返回以下内容：

• 标题；
• 3–8 个重要标签或分类标签；
• 归档状态；
• 条目链接或标识符（如可用）。

需清晰区分：

• 元数据写入成功与否；
• 图像上传成功与否；
• 部分成功情形。

最小检索输出

至少返回以下内容：

• 默认返回 1–3 个高质量匹配项；
• 每项匹配的简短标题；
• 每项匹配的 1–2 行理由说明；
• 在支持前提下返回图像预览，否则返回条目链接。

除非用户明确要求，否则不得直接输出原始数据库记录。

存储模型指导原则

本能力具备后端感知能力，但顶层逻辑应保持后端无关性。

前置条件与后端要求

仅当运行时已具备合适存储后端访问权限时，方可启用本能力。

本能力所需的后端凭证取决于所选存储后端。 对于基于 Notion 的归档或检索流程（涉及读写 Notion 数据库），运行时中应已配置 NOTION_API_KEY。 仅元数据分析可在无后端写入权限条件下继续执行。

基于 Notion 的使用前提

若以 Notion 作为存储后端，用户应已具备以下条件：

• Notion 账户；
• Notion 集成或 API 密钥；
• 目标 Notion 数据库，或可创建新数据库的父级页面；
• 将该数据库或页面与集成关联的权限。

若缺少上述前提，本能力仍可分析图像并生成结构化元数据，但无法完成基于 Notion 的归档。

最低要求：

• 运行时可从当前渠道或本地路径读取源图像；
• 运行时可分析图像，或至少能以低置信度元数据方式保存图像；
• 运行时可在目标后端创建、更新和查询记录；
• 运行时可在该后端附加或引用原始图像；
• 运行时可向用户返回图像预览或链接。

若使用 Notion 作为后端存储：

• 运行时必须已具备正常工作的 Notion 集成或 API 访问能力；
• 目标数据库必须已存在，或可由运行时创建；
• 运行时必须具备目标数据库的读写权限；
• 数据库 ID、页面 ID 等标识符必须保持可配置；
• 若无法找到目标数据库，应询问用户库应存放于何处，以及是否应在该处创建新数据库；
• 仅当父级页面/位置已知且无歧义时，才自动创建 Notion 数据库；
• 本公开能力不包含个人凭证或私有 workspace 配置。

在 OpenClaw 架构中，假设后端集成需在能力外部完成配置。 若缺失后端访问能力，不得假装归档或检索成功；应尽可能降级为图像分析、宽泛打标及结构化元数据输出。

理想的后端存储应支持：

• 标题字段；
• 图像/文件字段；
• 结构化元数据字段；
• 全文本搜索；
• 按单选/多选类属性过滤；
• 稳定的条目链接。

若使用 Notion 作为后端存储：

• 保持数据库 ID 及相关标识符可配置；
• 将原始图像存入专用的文件/图像属性；
• 若 API 路径要求，应将数据库/页面创建与文件上传分离；
• API 版本差异应在实现说明中注明，而非将个人 ID 硬编码进公开能力。

能力与降级规则

推荐按以下顺序执行：

1. 获取图像；
2. 分析图像；
3. 写入结构化元数据；
4. 附加原始图像；
5. 交付图像预览或结果链接。

若某项能力不可用，应优雅降级：

• 若图像分析不可用，则以宽泛标题与宽泛标签存储图像，并明确标记元数据为低置信度；
• 若无法直接附加图像，则在安全且支持的前提下存储来源链接或本地路径引用；
• 若无法交付图像预览，则改用标题、理由、标签与条目链接替代；
• 若后端仅支持部分结构化字段，应优先保留对检索最关键的字段：标题、摘要、页面类型、风格标签、图像/来源。

结果质量规则

优质归档结果

• 明确确认成功或部分成功；
• 展示生成的标题；
• 展示最重要标签；
• 清晰区分元数据写入与图像上传的成功状态。

优质检索结果

• 尽可能直接返回图像；
• 包含简洁理由说明；
• 帮助用户快速决策；
• 避免输出原始数据库记录。

失败处理

针对归档流程，将失败细分为：

• 图像获取失败；
• 分析失败；
• 记录创建失败；
• 图像上传/附加失败；
• 最终补丁/更新失败。

针对检索流程，将失败细分为：

• 查询意图解析失败；
• 数据库查询失败；
• 图像下载失败；
• 结果交付失败。

只要用户仍能获得可用结果，部分成功即属可接受。

若图像返回失败但文本检索成功，仍应返回：

• 标题；
• 理由；
• 关键标签；
• 条目链接；
• 并明确说明预览交付失败。

公开发布规则

公开发布本能力时需遵守：

• 移除私有 workspace ID、URL 及账号专属路径；
• 保持渠道处理逻辑通用化；
• 保持后端存储可配置；
• 将归档与检索均列为一级能力并加以说明；
• 明确声明检索应尽可能返回匹配图像；
• 避免嵌入个人工作流或私有凭证。

按需查阅参考文档

• 生成新图像结构化元数据时，参阅 references/analysis-schema.md；
• 适配聊天渠道图像输入时，参阅 references/channel-flow.md；
• 创建或审核目标 Notion 数据库结构时，参阅 references/notion-database-schema.md；
• 实现字段映射与标准化写入时，参阅 references/notion-mapping-spec.md；
• 向 Notion 记录附加原始图像时，参阅 references/notion-file-upload.md；
• 实现检索、排序及以图像为先的结果交付时，参阅 references/query-flow.md；
• 选择或扩展双语标签时，参阅 references/tag-vocabulary-v1.md。

适用范围

本能力适用于：

• 灵感归档；
• 设计参考检索；
• 视觉精选生成；
• 灵感库工作流。

请勿将本能力作为以下任务的主要工具：

• 正式 UX 审计；
• 无障碍审查；
• 重设计批判分析；
• 生产环境 UI 规范编写。