fix: v0.15 审查修复 — 文件名冲突、版本锁定、文档补全、降级路径

审查 Codex v0.15 后修复以下问题：

1. agent.md → AGENT.md：消除 macOS 大小写不敏感文件系统上的文件名冲突
2. HANDOFF.md：validator 规则数从"6 条"更正为"R1-R9"
3. makelive 版本锁定到 0.7.0（live-photo-production.md + package-live-photo.py）
4. 补充 Swift metadata helper 脚本的执行说明和依赖要求
5. platform-specs.md：将"Observed support"改为"截至 2026-07 实测"
6. SKILL.md：补充 GIF/MP4 降级路径，覆盖无法走 iPhone/AirDrop 的发布场景

由 Kiro (Claude Code) 完成审查和修复。

Co-Authored-By: Claude <noreply@anthropic.com>

HANDOFF.md

@@ -46,7 +46,7 @@ guizang-social-card-skill/
 │   ├── make-video-contact-sheet.py # Live Photo 视频抽帧 contact sheet
 │   ├── package-live-photo.py      # JPG+MOV 打包为 .pvt 的入口
 │   └── *.swift                    # Apple Live Photo metadata helper
-├── validate-social-deck.mjs   # 6 条规则的渲染后校验器
+├── validate-social-deck.mjs   # R1-R9 渲染后校验器
 ├── package.json / package-lock.json / node_modules   # 仅 playwright
 ├── .gitignore                 # v0.13 新增
 └── local-tests/               # 本地测试与素材（git 忽略，不随 skill 分发）

SKILL.md

@@ -311,6 +311,7 @@ Final response (after the user has reviewed or asked for auto-check) should incl
 - For any image fetched from the web: source URL + site + the attribution decision the user made.
 - For Live Photo: the `.pvt` package path, the debug `JPG + MOV` pair, target platform duration, and validation summary.
 - For Live Photo publishing: remind the user of two things: platform limits (`5s` Xiaohongshu, `3s` WeChat Official Account) and publish path (AirDrop the `.pvt` package as one item to iPhone, then publish from the matching mobile app path; desktop/web upload paths generally cannot recognize `.pvt` as a publishable Live Photo).
+- If the user cannot use the iPhone/AirDrop publishing path (e.g. desktop-only workflow, Android, or a platform that does not support Live Photo), offer a degraded delivery: export a short looping GIF or a silent MP4 clip from the same MOV source. The GIF/MP4 keeps the motion evidence but loses the Live Photo tap-to-play experience. Confirm with the user before switching to this fallback.
 - Any unresolved risks, such as source images being low resolution.
 
 ## Non-Negotiables

references/live-photo-production.md

@@ -209,9 +209,11 @@ Why this tool:
 Install or run with `uv`:
 
 ```bash
-uvx makelive IMG_TEST_LIVE.JPG IMG_TEST_LIVE.MOV
+uvx --from 'makelive==0.7.0' makelive IMG_TEST_LIVE.JPG IMG_TEST_LIVE.MOV
 ```
 
+Pin the version (`0.7.0` as of 2026-07) to avoid breakage from API changes in this small-audience package.
+
 For `.pvt`, use the Python API:
 
 ```bash
@@ -236,6 +238,24 @@ uvx --from makelive python scripts/package-live-photo.py IMG_TEST_LIVE.JPG IMG_T
 
 Use this wrapper when available so every run prints the asset id and `.pvt` path consistently.
 
+### Swift Metadata Helpers
+
+When `makelive` is unavailable or you need to add Apple Live Photo metadata manually, the repo includes two Swift scripts. They require macOS with the system Swift toolchain (Xcode or Command Line Tools) and AVFoundation.
+
+Write the MakerNote asset identifier into a JPEG:
+
+```bash
+swift scripts/add-livephoto-maker-note.swift input.jpg output.jpg <asset-id>
+```
+
+Write the QuickTime content identifier and still-image-time metadata into a MOV:
+
+```bash
+swift scripts/add-livephoto-mov-metadata.swift input.mov output.mov <asset-id>
+```
+
+Both scripts must receive the same `<asset-id>` (a UUID string) so iPhone Photos pairs the JPG and MOV as one Live Photo. Normally `makelive` handles this automatically; the Swift scripts are a fallback for environments where Python/uvx is blocked.
+
 ## Intake Decision Tree
 
 When the user provides video assets:

references/platform-specs.md

@@ -112,10 +112,10 @@ output/wechat-cover-pair-preview.png
 
 ## WeChat Official Account Article Live Photo
 
-Observed support is upload-path dependent:
+截至 2026-07 实测，Live Photo 支持与上传路径相关：
 
-- iPhone upload can preserve Live Photo in Official Account article editing.
-- Web upload does not expose the same Live Photo path.
+- iPhone 端上传可在公众号文章编辑中保留 Live Photo。
+- 网页端上传没有对应的 Live Photo 入口。
 - Keep Live Photo duration at or below `3s`.
 - Publish path: AirDrop the `.pvt` package as one item to iPhone, then upload from the iPhone Official Account article editing path.
 

scripts/package-live-photo.py

@@ -5,7 +5,7 @@ Run with:
 
   UV_CACHE_DIR=/private/tmp/uv-cache \
   UV_TOOL_DIR=/private/tmp/uv-tools \
-  uvx --from makelive python scripts/package-live-photo.py IMG.JPG IMG.MOV
+  uvx --from 'makelive==0.7.0' python scripts/package-live-photo.py IMG.JPG IMG.MOV
 """
 
 from __future__ import annotations