点睛
为已经完成或接近发布的代码库完成视觉风格设计与装修，让仓库从“放代码的地方”变成美观、可信、易懂、可安装、可传播的产品门面。
把一个完成的产品转化为别人看得懂、信得过、装得上、会使用、愿意传播的公开仓库。把美观、动效和可信度作为同一项产品交付，而不是只改 README 文案或堆装饰图片。
不可妥协的规则
- 先核验产品，再包装产品。 确认真实仓库边界、当前提交、运行状态、功能、许可证、发布渠道和已有素材。不要发明功能、指标、用户评价、兼容性或发布状态。
- 先审计，后修改。 先运行
scripts/audit_repository.py，阅读源码入口、产品文档、现有 README、资产和 Git 状态。保留用户已有修改，不覆盖无关工作。 - 产品价值先于安装说明。 README 先回答“这是什么、给谁、解决什么、真实状态如何”，再进入安装、首次成功、升级和排错。
- 真实素材优先。 优先复用真实 Logo、产品截图、界面录屏和输出结果。新生成的视觉只能解释真实产品，不能伪造尚不存在的界面或能力。
- 动效机会必须评估。 每次都评估动态 Hero、真实操作 GIF、演示视频和 Release 媒体；只有 README 无法承载关键体验时才评估展示网站。不得默认只交付静态 README，也不得为了显得高级而默认建站。动效不改善理解、信任或品牌时，记录不采用原因。
- 平台能力必须分层。 README、Social Preview、Release 媒体和 GitHub Pages 是不同表面。不要把 README 当成可任意运行 JavaScript、CSS 或动画 SVG 的网页。
- 美观必须可用。 动效不延迟关键信息，提供静态首帧和
prefers-reduced-motion，检查移动端、深浅背景、文件大小、循环节奏和许可证。 - 能力本体与分发层分开。 产品源码、Skill、插件、安装器、官网和市场配置只有在真实存在时才写入；避免复制出第二份会漂移的核心实现。
- 发布状态按证据表达。 分开本地完成、远端推送、Tag、Release、可安装、首次使用、真实行为验证和官方目录/商店状态。
- 远端动作不自动授权。 本地装修请求允许修改目标仓库内相关文件；推送、创建 Release、修改仓库 Settings、上传 Social Preview、启用 Pages 或部署仍需用户明确要求。
工作流
1. 界定交付与权限
确认目标仓库和本轮终点：
- 只输出装修方案
- 完成本地仓库装修
- 加入动态 README
- 评估并按需建设展示网站
- 准备发布但不推送
- 完成远端发布与公开验收
若用户说“装修好”“直接做”，默认完成安全的本地实现与验证；不要因此推送或修改远端设置。
2. 审计真实仓库
运行：
python3 <skill-dir>/scripts/audit_repository.py <repo-path>
再读取 audit-and-positioning.md，核验：
- Git 根目录、remote、当前分支/提交、工作区修改
- 产品真实入口、可运行程度、许可证、版本和发布渠道
- README、docs、治理文件、测试和 Release 记录
- Logo、截图、录屏、GIF、视频、社交图和已有官网
- 本机绝对路径、占位文案、断开的相对链接和疑似敏感文件
不要把 not a git repository 直接诊断成发布失败；先定位真正 checkout。不要修改用户未授权的产品逻辑。
3. 建立产品装修简报
从真实材料提炼：
- 用户交给产品什么
- 产品完成什么
- 用户最终得到什么
- 最适合谁、不适合谁
- 一个最强差异点
- 当前真实状态和重要边界
- 希望传达的气质
- 第一次成功的定义
需要落盘时复制并填写 repository-brief-template.md。缺少品牌方向时根据产品本身做一套明确选择，避免把设计决策全部推回用户。
4. 选择必做底座与条件模块
先完成所有公开仓库都需要的底座，再按产品任务选择模块。不要把模块数量当作完成度或高级程度。
必做底座：
- 产品定位与事实边界
- README 信息架构
- 安装与第一次成功
- 真实视觉素材
- 许可证、版本和发布状态
- 基础治理与公开验收
条件模块：
| 模块 | 采用条件 |
|---|---|
| 动态表达 | 动态 Hero、真实操作 GIF 或视频能明显改善理解、信任或品牌识别 |
| 展示网站 | README 无法承载关键交互、视觉体验、非开发者转化或在线 Demo，且没有可复用的正式官网 |
| 发布传播 | 产品确实进入版本发布、外部分享或持续传播阶段，需要 Social Preview、Release 媒体、双语入口或升级排错 |
| 深度文档 | 安装、API、配置或维护复杂到 README 已不适合作为唯一文档 |
展示网站是条件性交付，不是更高装修等级。Agent Skill、CLI、SDK、小型库通常以 README 为主页；UI 产品、游戏、创意编码、交互 Demo 或面向非开发者的产品更可能需要展示网站。产品已有正式官网时，优先连接并复用，不再创建重复的 GitHub Pages。
5. 设计 README 与文档
读取 readme-and-documentation.md。按用户理解路径组织：
看懂产品
→ 建立使用动机
→ 看见真实证据
→ 理解能力与边界
→ 安装
→ 完成第一次成功
→ 排错与升级
→ 了解测试、维护与许可证
不要机械套模板。CLI、库、App、网站、Skill/插件和研究项目应选择不同的演示、安装和首次成功路径。需要骨架时复制 readme-outline-template.md 后按产品删改。
6. 设计视觉与动效系统
读取 visual-and-motion.md。先盘点真实资产，再确定一套产品专属的色彩、字体、构图、图标与动效语言。
如果 motion-anything-design 可用，必须先：
- 读取当前 bundle。
- 搜索适合产品气质的设计系统。
- 搜索
implementation_status: ready的真实动效。 - 读取入选动效的
avoid_when、restraint、reduced_motion、依赖和许可证。 - 获取真实实现文件后再适配；不要凭记忆重写已有实现。
- 搜索并获取准确图标 SVG。
若需要新 Logo、Hero 或插图，先复用已有品牌资产；确需生成时使用可用的图像生成能力，并以真实产品截图和界面为依据。
每个仓库至少完成一次动效机会审计：
- 动态品牌 Hero 是否能更快说明产品
- 一个真实操作 GIF 是否比多张截图更有效
- Release 是否需要短视频
- README 是否已经无法承载关键体验；若是，现有官网或展示网站是否值得承载交互、流程和 CTA
- 静态首帧、无动画状态和深浅背景是否都成立
7. 实现仓库门面
在目标仓库现有技术栈和约定内工作：
- 修改 README 和必要文档
- 复用或制作真实视觉媒体
- 按需增加
docs/、上手、排错、维护和发布说明 - 通过展示网站条件门后，才按需增加 Pages 源码与部署配置
- 保持产品核心源码单一，不为了展示复制实现
- 使用相对链接，避免本机路径
- 不提交密钥、Cookie、私有链接、未授权素材或不兼容许可证
动效选择遵循“一项动效承担一个叙事任务”。默认每屏最多一个环境背景效果、一个主要文字动效和一个庆祝/高光效果；正文与关键操作保持稳定。
8. 验证本地结果
重新运行审计脚本，并检查 Git diff。然后：
- 渲染 README，检查桌面与窄屏阅读顺序
- 实际打开所有图片、GIF 和视频
- 检查 GIF 首帧、循环接缝、字幕和文件大小
- 若采用展示网站模块，对 Pages 或现有官网执行浏览器验收：响应式、深浅模式、交互、控制台、性能、404
- 开启减少动态偏好，确认内容立即可见且功能不丢失
- 检查所有相对链接、安装命令、版本、许可证和真实状态
- 确认没有覆盖用户无关修改
9. 验证公开产物
用户授权发布后，读取 release-and-acceptance.md。从公开仓库或 Tag 全新检出，重新验证 README、媒体、已采用的展示网站、安装、第一次成功和升级路径。
分别报告：
- 本地装修完成
- 远端源码可见
- Tag / Release 已发布
- 已采用的 Social Preview / 展示网站已生效
- 用户首次成功已验收
- 尚未完成或仅由用户口头确认的部分
需要正式记录时复制 acceptance-report-template.md。
停止条件
- 产品真实状态无法确认：先报告证据缺口，不用视觉掩盖问题。
- 缺少真实产品画面：可以制作品牌与结构素材，但不要伪造产品截图。
- 动效与 README 不兼容：优先转成 GIF 或视频；只有通过展示网站条件门时才转到 Pages，不声称 README 会运行不受支持的脚本。
- 现有工作区修改与装修文件冲突：保留用户修改并说明冲突，必要时请求方向。
- 需要推送、部署、付费素材或修改远端设置但未获授权：完成本地可交付部分后停止。