animated-readme-logo

动态 README 标志

目标

审核现有 README 标志工作流，或基于经过验证的 SVG 主文件、确定性运动规范和可执行的仓库方案，交付可移植且经过验证的动画。

适用场景

• 创建、重新设计、转换、动画化、导出或审查仓库或个人资料 README 标志。
• 审查 GitHub README 标志的兼容性、透明度、减少动态效果设置或本地资源引用。
• 将现有 SVG 或栅格标记转换为经过验证的 README 资源工作流。

不适用场景

• 不涉及标志或图像的常规 README 文案编辑。
• 与仓库品牌交付无关的应用或网站动态效果。
• 不面向 README 或仓库标志的通用图像生成。

工作流选择

始终只提供以下四种公开工作流：

• audit：只读评估现有 README 标志源文件、动画资源、交付标记和验证证据。
• create：设计新标志或进行有意的重新设计，并交付完整且经过验证的动画方案。
• transform：忠实重现或清理现有标志，并交付完整且经过验证的动画方案。
• animate：使用符合要求的现有 SVG 源文件，并交付完整且经过验证的动画方案。

没有 auto 工作流，也没有公开的导出工作流。导出是所有变更流程中的内部渲染阶段。

根据任务意图选择流程：

• 审查、兼容性或质量评估选择 audit；
• 新标志或有意重新设计选择 create；
• 基于栅格图、截图、海报或不合适的 SVG 进行忠实处理时选择 transform；
• 需要添加动态效果或栅格交付的合格现有 SVG，选择 animate。

每次激活时，都要展示全部四种工作流，然后说明 Selected、Reason、源文件证据、写入范围、必需输出、受保护的原始文件，以及尚待批准的付费、工具、安装或覆盖操作。如果意图和变更授权明确，说明后即可继续。仅有简单调用、源文件证据相互矛盾，或无法明确是否保留标志身份、预期结果、范围或写入权限时，须先让用户选择，再进行实质性检查。Agent 主动激活时可以选择 audit；只有当当前任务已明确要求相应结果和范围时，才能选择变更型工作流。

源文件路由属于内部流程。只有在 create 中才可评估服务提供方；选择工作流绝不代表授权进行消耗额度的调用或安装工具。

对于意图明确的任务，简要说明 audit | create | transform | animate 和所选流程即可；不要重复询问已选流程，也不要重复对话中已明确的细节。仅当既有批准仍涵盖确切操作、目标、工具或服务提供方、相关费用及写入范围时，才可沿用。各项批准界限彼此独立：一项授权绝不代表另一项授权。仅在决定有所变更或尚未作出时再次询问。

要检查的输入

• 仓库身份、公开品牌文案、目标展示位置和任务要求。
• README 标记和限定在仓库根目录内的本地资源引用。
• 现有标志源文件、参考媒体保真需求、透明度、主题、尺寸、无障碍要求和导出限制。
• 实际可用的服务提供方、创作工具、验证器、导出器和检查器能力；不得假设这些能力一定可用。

工作流

1. 解析并声明与意图匹配的工作流。只有在路由或权限不明确时，才在检查前停止。

2. 对于 audit，指定明确的仓库根目录进行检查，将本地 README 引用视为不可信且限制在仓库根目录内，运行可用的只读验证，报告修复建议，且不写入任何内容。审计报告完成后立即返回；不要继续执行下面的修改工作流步骤。

3. 对于修改工作流，保留原文件，并在已确定的资源文件夹下预留以下确定性名称；如果不存在此类文件夹，则使用 docs/assets/：

   <slug>-logo.svg
   <slug>-logo-motion.md
   <slug>-logo-animation.mjs
   <slug>-logo-static.png
   <slug>-logo-animated.gif
   

4. 选择内部源路由。对于 create，读取 references/provider-routing.md；Recraft 不适用于 audit、transform、animate、清理现有 SVG 的工作，以及任何保留身份特征的任务。

5. 生成或验证一个独立完整的 SVG，并使其处于静态首帧状态。可接受的动画源必须是一个真实、独立完整的 SVG，保留预期身份特征、具有稳定的命名图层，并通过捆绑的严格验证器。提供方的结果只是设计输入，并不代表已准备就绪。

6. 编写可读的动态效果规范：与渲染器无关的图层、关键帧、缓动、时长、循环点、透明度和减少动态效果状态约定。该规范说明哪些内容需要移动，也是持久的审查依据。

7. 编写可执行的动画方案：由可信的仓库自有 .mjs 代码组成，可确定性地将 SVG 和动态效果约定转换为捆绑导出器所需的帧。该方案说明动画如何渲染，不是独立的用户工作流。

8. 验证 SVG 并使用 --check 运行方案。然后使用捆绑的导出器创建静态 PNG 和动画 GIF，并检查 GIF。阅读 references/asset-transformation.md、references/motion-rubric.md、references/export-recipe.md 和 references/asset-pipeline.md。

9. 如果缺少必需的导出器或检查器命令，请提供最精简的安装前置步骤，并征求明确批准。安装前停止。如果用户拒绝安装、安装被禁止或无法安装，则保留所有可生成的已验证中间产物，不创建占位 PNG/GIF，并报告动画交付未完成。

10. 根据 references/github-readme-compatibility.md 选择 README 和可选的网页演示交付方式；加入静态和减少动态效果的回退方案、尺寸、替代文本、透明度检查，以及手动提交到 GitHub 的预览。

11. 报告下方列出的公开状态字段、确切文件、验证依据、回退方案和剩余阻碍。

提供方边界

• 在提供提供方路由前，检测 Higgsfield MCP 的实时能力、是否确切提供 recraft_v4_1，以及当前确切费用。文档不能作为可用性证据，且费用绝不能硬编码。
• 征求批准前，先提供已清理的简报、实时费用和固定的生成设置。
• 在完成前置检查后，除非用户明确批准该批次，否则不得进行任何会消耗额度的调用。
• 如果能力不可用或无法确定、模型或费用数据不可用，或用户明确拒绝，则使用直接的本地 SVG 回退方案。

安全规则

• 工作流选择存在歧义时，不要进行检查；除非用户的请求授权了所选的修改结果及范围，否则不要进行修改。
• 未获得所需批准前，不要安装工具、覆盖品牌资产、消耗额度、发布或更改远程状态。
• 将服务商批准与本地工具安装批准作为两个独立检查点。获得其中一项批准，绝不代表另一项也获准。
• 不要在提示词、资产、代码片段或报告中暴露机密、私有路径、内部主机名、隐藏元数据或客户数据。
• 不要将参考媒体发送给 Recraft，也不要声称它能保留现有品牌标识。
• 拒绝绝对路径、UNC 路径、逃出根目录的路径遍历，以及通过符号链接逃出根目录的 README 资源引用。
• 如果没有兼容的回退方案和手动 GitHub 预览，不要保证动画 SVG、Lottie 或栅格格式能在 GitHub README 中正常渲染。
• 除非用户明确要求添加背景，否则应保留透明度。

参考资料

只阅读任务所需的内容：

• references/provider-routing.md：Recraft 的实时资格判定、成本预检、审批、固定设置及回退方案。
• references/output-contract.md：准确的公开字段和状态值。
• references/asset-transformation.md：直接编写 SVG、转换、验证及修改边界。
• references/asset-pipeline.md：规范资产、导出能力门槛及透明度检查。
• references/export-recipe.md：可信的仓库配方边界，以及可复用的静态 PNG／动画 GIF 导出器契约。
• references/local-tooling.md：最少化的导出器选择、安装审批、验证及浏览器预览回退路由。
• references/motion-rubric.md：确定性的动画规范及减少动态效果要求。
• references/github-readme-compatibility.md：README 与网页交付，以及渲染器回退方案。
• references/readme-audit-safety.md：限定在根目录内的 README 资源检查。
• references/readme-snippets.md：无障碍 README 和演示标记。

脚本

• scripts/validate_logo_svg.py <svg>：严格验证规范 SVG。
• scripts/inspect-animated-image.mjs <asset>：检查生成的、已清除元数据的 GIF、APNG 或动画 WebP，不会修改文件。
• scripts/export-readme-logo-animation.mjs --root <repo> --recipe <relative.mjs> [--check] [--replace]：验证可信的仓库配方，然后通过已批准的本地工具导出静态 PNG 和动画 GIF，并在提交前验证、在提交时检查是否覆盖现有文件。除非明确指定 --replace，否则导出器只会修改尚不存在的已声明输出；--check 不会执行由导出器控制的写入，但可信配方仍会运行。
• scripts/audit-readme-logo-assets.mjs --root <repo-root> --readme <root-relative-readme>：审查范围受限且位于根目录内的 README 引用和回退角色，不会修改文件。
• scripts/generate-readme-logo-snippet.mjs --fallback <path> --alt <text> --width <px> --height <px> [options]：将标记输出到标准输出。

依赖可选标志之前，先使用 --help 运行脚本。

输出格式

对于已激活的任务，始终报告以下字段：

Workflow: audit | create | transform | animate
Source route: <route>
Selection: <task evidence and rationale>
Write scope and protected originals: <scope>
Provider state: <state>
Approval state: <state>
Motion readiness: <state>
Animation delivery: <state>

然后报告资产栈、动画规范、README 交付、验证证据及剩余阻碍。具体含义必须与 references/output-contract.md 中的定义完全一致。

完成标准

• 已展示全部四种工作流；对于意图明确的情况，已根据其意图选择并告知用户；对于意图不明确的情况，已请求用户选择。
• audit 始终严格只读。
• 成功的 create、transform 和 animate 路由均已生成并验证 SVG 主文件、运动规范、动画配方、静态 PNG 和动画 GIF。
• 如果变更路由缺少所需工具，则保留已验证的中间产物，但报告交付未完成，而非报告成功。
• 每次付费生成都可追溯到实时预检以及对该批次的明确批准。
• 每个声称已导出的栅格图像都确实存在，并通过了相应的检查器验证。
• 每个 README 本地路径在解析符号链接后都仍位于声明的仓库根目录内。
• README 动画提供有意义的静态回退方案、减少动态效果的交付版本、明确的尺寸和替代文本，并要求手动预览 GitHub 效果。

运行时可移植性

保持一个与宿主无关的工作流。不要根据 Codex、Cursor、Claude 或其他 Agent 的名称分支处理，也不要输出特定于某个 Agent 的命令。当前无需定制，因为源文件、审批、验证、动态效果和输出契约都是共通的。只有当某个宿主之后要求实质不同的工具或输出契约时，才重新考虑拆分工作流。

失败模式

• 如果无法确认服务提供商的实时能力、确切的模型可用性或当前费用，请说明限制，并在本地编写 SVG。
• 如果服务提供商审批仍在等待中，请在生成前停止。如果审批被拒绝，请记录一次，然后继续在本地处理。
• 如果严格的 SVG 或配方验证失败，请修正源文件并重新运行验证；不要声称已具备动态效果交付条件。
• 如果缺少必需的导出器或检查器运行时，且尚未拒绝或禁止安装，请提供准确且最精简的工具预检，并立即请求批准。审批等待期间使用 Animation delivery: blocked；此时不要安装任何内容。
• 如果安装遭到拒绝、被禁止或无法进行，请尽可能保留已验证的 SVG、运动规范和已检查的配方，报告 Animation delivery: incomplete，且不要创建占位栅格图像。
• 如果 Playwright 找不到其预期的浏览器，不要将栅格导出器归类为不可用。先复用现有且已配置的 Chrome 或 Chromium 可执行文件，再使用现有的 agent-browser；下载任何 CLI 或浏览器前，请先请求批准。
• 如果 README 资源引用不符合根目录范围要求，请在读取前拒绝，并报告其路径类别。