diff --git a/.spec/specs/2026-10-25_add-media-and-polish/spec.md b/.spec/specs/2026-10-25_add-media-and-polish/spec.md
new file mode 100644
index 0000000..229d80e
--- /dev/null
+++ b/.spec/specs/2026-10-25_add-media-and-polish/spec.md
@@ -0,0 +1,73 @@
+# 媒体支持（图/视频/音频）+ 灯箱按钮与评论区美化 - 项目范围
+
+<!-- spec-format: 2 -->
+
+## 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 待确认问题
+- [x] 图/视/音三媒都要 → 用户明示
+
+### 2.4 可选解释与取舍
+- 视频/音频用原生 <video>/<audio> 标签（markdown raw HTML）> 自研指令解析器（:::video 语法）-> 选原生（零解析器、写作直观、降级天然）
+- 评论区美化走页面级 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）
diff --git a/.spec/specs/2026-10-25_add-media-and-polish/tasks.md b/.spec/specs/2026-10-25_add-media-and-polish/tasks.md
new file mode 100644
index 0000000..99e1083
--- /dev/null
+++ b/.spec/specs/2026-10-25_add-media-and-polish/tasks.md
@@ -0,0 +1,42 @@
+# 媒体支持（图/视频/音频）+ 灯箱按钮与评论区美化 - 任务拆解
+
+## 使用规则
+- boundary/verify 齐备；verify 只读断言
+
+## 阶段一：实现
+
+- [ ] T1 灯箱原图/下载按钮美化
+  - claim: orchestrator
+  - boundary: 只改 GalleryPage.astro 灯箱 lb-orig 区（升级为与 lbnav 同语言的胶囊按钮：图标+文字+悬停态）
+  - verify: `pnpm astro build && grep -q "lb-orig" dist/gallery/index.html`
+
+- [ ] T2 Artalk 评论区美化
+  - claim: op-gitea（mesh 车道，预约 src/components/ArtalkComments.astro）
+  - boundary: ArtalkComments.astro 内注入页面级覆盖样式（.atk-* 选择器，用 tokens 变量，明暗双态随 [data-theme]）；可调研 Artalk darkMode 配置项并在 init 传参；不改 Artalk 服务端
+  - verify: `pnpm astro build && grep -q "atk-" src/components/ArtalkComments.astro`
+
+- [ ] T3 markdown 媒体支持
+  - claim: orchestrator
+  - boundary: src/styles/global.css 增媒体样式段（.prose-reading/.prose-tech 内 img/figure/video/audio：宽度/圆角/居中/图注样式）；验证 raw HTML 透传与图片优化
+  - verify: `pnpm astro build`
+
+- [ ] T4 三媒样张
+  - claim: op-artalk（mesh 车道，预约 content/posts/media-sample.md 与其资产目录）
+  - boundary: ffmpeg 生成 3s 测试视频（<1MB）与 3s 音频；一张测试图；写一篇 draft:true 的样例文章（category: tech, draft 置 true 不上线仅构建验证）三媒齐用；不碰既有六篇
+  - verify: `pnpm astro build && grep -q "<video" dist/archives/*/index.html -r | head -1`
+
+- [ ] T5 写作指南
+  - depends-on: task_0003
+  - claim: orchestrator
+  - boundary: 新建 docs/写作指南.md（三媒插入语法/资产目录约定 content/posts/assets/{slug}/）/体积纪律（图≤1MB 压缩后、音≤5MB、视频>5MB 走仓外 store+绝对 /media/ 路径待 build.sh 同步）
+  - verify: `test -s docs/写作指南.md`
+
+- [ ] T6 验证收官
+  - depends-on: task_0001, task_0002, task_0004, task_0005
+  - claim: orchestrator
+  - boundary: E2E 复跑 + 样例页与评论区双主题截图交视觉模型 + 归档推送
+  - verify: `node tests/e2e.mjs 2>&1 | grep -q "30/30 PASS"`
+
+---
+
+**当前进度**：由脚本计算，无需手动维护