wait4xandGLM-5.3
6da2b7cecf
spec_verify --all 六项同指纹 exit=0；视觉终审+复验双轮 可上线 Spec: 2026-10-25_add-media-and-polish Co-authored-by: GLM-5.3
3.4 KiB
3.4 KiB
媒体支持（图/视频/音频）+ 灯箱按钮与评论区美化 - 项目范围
1. 问题定义
- 项目目标：书评/技术文 markdown 支持插入图片、视频、音频（含样式与工作流文档）；灯箱原图/下载按钮与 Artalk 评论区视觉美化对齐站点设计系统
- 目标用户：站长（多媒体写作能力）与读者（一致的视觉体验）
- 核心价值：内容表达力补全（三轨中的摄影/技术教程常需媒体）+ 收尾两处观感
2. 假设与待确认
2.1 已确认事实
- ffmpeg 7.1.5 可用（测试媒体生成）
- Astro 5+ 内容集合 markdown 正文相对路径图片走图片服务优化；raw HTML（video/audio 标签）默认透传
- Artalk 2.x 支持 CSS 变量主题（--at-* 系）与 darkMode 配置
2.2 关键假设
- 视频进 git 仓在短小（<5MB）场景可接受；大视频走仓外 store（photos-originals 同模式）+ /media/ 路径
- Artalk 页内渲染可被页面级 CSS 覆盖定制（同源同文档）
2.3 待确认问题
- 图/视/音三媒都要 → 用户明示
2.4 可选解释与取舍
- 视频/音频用原生
- 评论区美化走页面级 CSS 覆盖 > fork Artalk 主题 -> 选覆盖（升级安全）
2.5 已证伪路径
- 无
3. 功能范围
3.1 核心功能（MVP）
- T1 灯箱原图/下载按钮美化
- T2 Artalk 评论区美化（tokens 对齐 + 明暗双态）
- T3 markdown 媒体支持（图片优化+样式+图注；video/audio 原生标签+统一样式）
- T4 测试样张（ffmpeg 生成音视频样例 + 含三媒的样例文章）
- T5 写作指南（docs/写作指南.md：三种媒体的插入方法/体积纪律/目录约定）
- T6 E2E + 视觉复核 + 收官上线
3.2 扩展功能
- 文内图片点击放大（复用灯箱）——二期
3.3 不在范围内
- 图库页媒体扩展、字幕、播放列表
4. 最小实现路径
- 最简单可行方案：原生标签 + global.css 媒体样式段 + 样例验证 + 指南文档
- 暂不引入：rehype 插件链、指令语法、媒体转码管线
- 不做的抽象/配置化：多媒体源管理界面
5. 技术决策
- 技术栈：Astro markdown 原生能力 + CSS
- 证据协议：evidence: runs
- 本轮允许改动：src/styles/、src/components/（ArtalkComments/GalleryPage）、content/posts（样例）、docs/、tests/
- 本轮不应触碰：infra 生产面、content/posts 既有六篇正文
- Git integration branch：
spec/2026-10-25_add-media-and-polish
5.1 验证策略
- 范围级别：package
- 变更对象：媒体样式与组件、样例内容、指南文档
- 快速检查：
pnpm astro build - 集成检查：
node tests/e2e.mjs - 全项目检查：视觉复核样例页与评论区双主题截图；仅在组件骨架或发布链变更时升级范围
- 升级触发：只有改动 Artalk 集成骨架或发布链时，才升级验证范围并记录理由
6. 成功标准与验证方式
- 样例文章三媒齐渲染（断言 video/audio/img 元素存在） -> verify: task_0004
- 评论区双主题截图过视觉审 -> verify: task_0006
- E2E 30/30 保持全绿 -> verify: task_0006
7. 风险与约束
- 大视频入仓风险 → 指南纪律 + photos-ingest 类体积闸（后续可加 media-ingest）