release: v0.8.8 混合流升级与图片标题修复

ChanMo · ChanMo · commit 2afe6537151e · 2026-02-22T17:07:10.000+08:00
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 TikLocal's main features include:
 
-* **A TikTok-like swipe-up browsing experience** that allows you to easily and quickly browse local video files.
+* **A TikTok-like swipe-up browsing experience** with a mixed feed of local videos and images.
 * **A file manager-like directory browsing** feature that allows you to easily find and manage local video files.
 * **A Pinterest-like grid layout** feature that allows you to enjoy local images.
 * **Support for light and dark modes** to suit your personal preferences.
@@ -19,7 +19,7 @@ TikLocal is suitable for the following use cases:
 
 * You don't trust TikTok's teen mode and want to provide your child with completely controllable video content.
 * You want to browse and manage your local videos and images locally, but don't want to use third-party cloud services.
-* You want to use a TikTok-style video browsing experience on your phone or tablet.
+* You want to use a TikTok-style mixed media browsing experience on your phone or tablet.
 * You want to use a Pinterest-style image browsing experience on your phone or tablet.
 
 ## How to use
@@ -105,13 +105,27 @@ brew install yt-dlp gallery-dl ffmpeg
 sudo apt install yt-dlp gallery-dl ffmpeg
 ```
 
+### Home Mixed Feed
+
+The home page (`/`) now uses a mixed immersive feed:
+
+- Videos and images are mixed in one swipe flow (video-first density, randomized order)
+- Image cards support in-feed AI caption/tags panel
+- Image cards support circular magnifier (2.5x / 5x)
+- Image cards do **not** auto-advance; swipe manually to move next/previous
+
 ### Configuration
 
 TikLocal provides some configuration options that you can adjust to your needs.
 
 * **Light and dark modes:** You can choose to use light or dark mode.
 * **Video playback speed:** You can adjust the video playback speed.
 
+## Documentation
+
+- Docs index: `docs/README.md`
+- Release notes: `docs/release_notes.md`
+
 
 ## TODO
 
diff --git a/README_zh.md b/README_zh.md
@@ -8,7 +8,7 @@
 
 TikLocal 的主要功能包括：
 
-* 提供类似 **Tiktok** 的 **上下滑动浏览** 体验，让您可以轻松快速地浏览本地短视频文件。
+* 提供类似 **Tiktok** 的 **上下滑动浏览** 体验，首页可混合浏览本地视频与图片。
 * 提供类似 **普通文件管理器** 的 **目录浏览** 功能，让您可以方便地查找和管理本地短视频文件。
 * 提供类似 **Pinterest** 的 **网格布局** 功能，让您可以欣赏本地图片。
 * 支持 **浅色和暗色模式**，满足您的个人喜好。
@@ -19,7 +19,7 @@ TikLocal 适用于以下场景：
 
 * 您不相信Tiktok的青少年模式, 想给你的小孩提供完全可控的短视频内容。
 * 您想在本地浏览和管理您的短视频和图片文件，但不想使用第三方云服务。
-* 您想在手机或 Pad 上使用 Tiktok 式的短视频浏览体验。
+* 您想在手机或 Pad 上使用 Tiktok 式的视频+图片混合浏览体验。
 * 您想在手机或 Pad 上使用 Pinterest 式的图片浏览体验。
 
 ## 如何使用
@@ -103,13 +103,27 @@ brew install yt-dlp gallery-dl ffmpeg
 sudo apt install yt-dlp gallery-dl ffmpeg
 ```
 
+### 首页混合流（Feed）
+
+首页（`/`）已升级为混合沉浸流：
+
+- 视频与图片在同一条滑动流中混排（视频主导密度，顺序随机化）
+- 图片条目支持 AI 标题/标签面板（站内生成与展示）
+- 图片条目支持圆形放大镜（2.5x / 5x）
+- 图片条目不自动跳转，需手动滑动切换
+
 ### 配置
 
 TikLocal 提供了一些配置选项，您可以根据自己的需要进行调整。
 
 * 浅色模式/暗色模式：您可以选择使用浅色模式或暗色模式。
 * 视频播放速度：您可以调整视频播放速度。
 
+## 文档
+
+- 文档索引：`docs/README.md`
+- 版本记录：`docs/release_notes.md`
+
 
 ## TODO
 
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,10 @@
+# 文档索引
+
+## 说明
+
+本目录用于沉淀 TikLocal 的关键设计决策、版本变更与实现约束，减少后续迭代时的重复讨论与回归风险。
+
+## 文档列表
+
+- `docs/mixed-feed-design.md`：首页混合流（视频+图片）设计与实现说明。
+- `docs/release_notes.md`：版本发布记录与未发布变更清单。
diff --git a/docs/mixed-feed-design.md b/docs/mixed-feed-design.md
@@ -0,0 +1,58 @@
+# 首页混合流（视频+图片）设计说明
+
+- 状态: 已落地
+- 更新时间: 2026-02-22
+
+## 背景/目标
+
+- 首页原先是纯视频沉浸流，图片内容被分流到 Gallery，导致首页素材类型单一。
+- 目标是在不引入复杂配置的前提下，升级为统一的混合流，保持“视频主导”节奏，同时提升新鲜感。
+
+## 结论/方案
+
+- 后端新增 `GET /api/feed/mix`，统一返回 typed items（`video` / `image`）。
+- 前端首页改为单一 Feed 状态机，按条目类型切换播放与交互能力。
+- 图片条目复用 Gallery 的关键体验：AI 标题/标签、圆形放大镜、单击专注模式（仅隐藏左下信息层）。
+
+## 关键决策与理由
+
+- 混排策略使用“目标比例 + 轻随机 + 连续段约束”，而不是固定 `4V+1I`：降低用户可预测性，保持内容新鲜感。
+- 图片不自动切换：避免打断阅读图片细节，改为手动滑动控制节奏。
+- 视频与图片工具分离：视频不显示 AI 按钮，图片不显示倍速按钮，减少认知噪音。
+- 专注模式只隐藏左下 AI 信息层：保留右侧操作按钮，避免关键操作入口丢失。
+
+## 实施要点
+
+- 后端：
+1. 从推荐服务分别拉取视频与图片候选池。
+2. 基于 seed 的伪随机混排，保证分页行为稳定且可复现。
+3. 输出统一结构（`type/name/media_url/thumb_url/detail_url`）。
+- 前端：
+1. 统一 Feed 渲染（`video` 与 `img` 元素共用切换流程）。
+2. 按类型启用控件：仅视频显示进度/倍速，仅图片显示 AI/放大镜。
+3. 放大镜按 `object-fit: contain` 的真实内容框计算取样，避免横向压扁。
+
+## 影响范围
+
+- 首页沉浸流入口：`/`。
+- API：`/api/feed/mix`。
+- 交互行为：单击、双击、滑动、图片专注、图片放大与 AI 信息层展示。
+
+## 风险与权衡
+
+- 混排随机性提高后，单次浏览的可解释性会下降。
+- 采用固定内置比例（不放到 settings）降低了配置复杂度，但牺牲了用户级个性化调节。
+- 前端状态机复杂度上升，需要测试覆盖关键类型切换场景。
+
+## 后续事项
+
+- [ ] 增加混合流比例/连续段统计的轻量调试日志（仅开发模式）。
+- [ ] 增加首页混合流端到端测试（类型切换、控件显隐、手势行为）。
+- [ ] 评估后续“图片组（carousel）”条目形态，在不破坏当前手势模型下演进。
+
+## 相关文件/模块
+
+- `tiklocal/app.py`
+- `tiklocal/templates/tiktok.html`
+- `tests/test_feed_mix.py`
+- `docs/release_notes.md`
diff --git a/docs/release_notes.md b/docs/release_notes.md
@@ -1,5 +1,17 @@
 # Release Notes
 
+## Unreleased
+
+## v0.8.8 (2026-02-22)
+- 首页沉浸流升级为混合媒体 Feed：在同一滑动流中混排视频与图片，替代原纯视频首页链路。
+- 新增 `/api/feed/mix`，统一返回 typed media items（`video` / `image`），并使用“目标比率 + 轻随机约束”混排，避免固定节奏可预测性。
+- 首页图片条目复用 Gallery 关键交互：AI 标题/标签面板、2.5x/5x 圆形放大镜、单击专注模式（仅隐藏左下信息层）。
+- 交互收敛：视频不显示 AI 按钮，图片不显示倍速按钮；图片不再自动计时切换，改为手动滑动切换。
+- 修复首页放大镜取样计算：按 `object-fit: contain` 的真实内容框计算，避免横向压扁。
+- 修复首页图片 AI 标题/标签不显示问题：调整 `currentCaptionUri` 生命周期，避免异步回写被错误丢弃。
+- 清理首页混合流过期代码：移除无效 `controls-active` 状态切换与不可触发的播放图标点击监听。
+- 新增 `tests/test_feed_mix.py` 覆盖混合 Feed API 基本行为，并新增混合流设计文档索引。
+
 ## v0.8.7 (2026-02-21)
 - 新增“来源回跳”能力：下载成功后将文件与原始 URL 建立映射，并新增 `~/.tiklocal/download_sources.json` 持久化来源索引。
 - 新增来源解析三层兜底：优先来源映射，其次 `.info.json`（`webpage_url/original_url`），最后按文件名结构推断平台链接（x/youtube/tiktok/instagram）。
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "TikLocal"
-version = "0.8.7"
+version = "0.8.8"
 description = "A local media server that combines the features of TikTok and Pinterest"
 authors = ["ChanMo <chan.mo@outlook.com>"]
 readme = "README.md"
diff --git a/tests/test_feed_mix.py b/tests/test_feed_mix.py
@@ -0,0 +1,74 @@
+import pytest
+
+from tiklocal.app import create_app
+
+
+@pytest.fixture
+def client(tmp_path, monkeypatch):
+    media_root = tmp_path / "media"
+    media_root.mkdir(parents=True, exist_ok=True)
+    (media_root / "v1.mp4").write_bytes(b"00")
+    (media_root / "v2.mp4").write_bytes(b"00")
+    (media_root / "nested").mkdir(parents=True, exist_ok=True)
+    (media_root / "nested" / "v 3.mp4").write_bytes(b"00")
+
+    (media_root / "i1.jpg").write_bytes(b"00")
+    (media_root / "i2.png").write_bytes(b"00")
+
+    data_root = tmp_path / "tiklocal-data"
+    monkeypatch.setenv("MEDIA_ROOT", str(media_root))
+    monkeypatch.setenv("TIKLOCAL_INSTANCE", str(data_root))
+
+    app = create_app({"TESTING": True, "MEDIA_ROOT": media_root})
+    return app.test_client()
+
+
+def test_mix_feed_returns_typed_items(client):
+    res = client.get("/api/feed/mix?page=1&size=12&seed=fixed-seed")
+    assert res.status_code == 200
+    data = res.get_json()
+
+    assert isinstance(data, dict)
+    assert "items" in data
+    assert "seed" in data
+    assert "has_more" in data
+
+    items = data["items"]
+    assert isinstance(items, list)
+    assert len(items) > 0
+
+    types = {item.get("type") for item in items}
+    assert "video" in types
+    assert "image" in types
+
+    for item in items:
+        assert "name" in item
+        assert "media_url" in item
+        assert "detail_url" in item
+        assert item["type"] in {"video", "image"}
+        if item["type"] == "video":
+            assert item["detail_url"].startswith("/detail/")
+        else:
+            assert item["detail_url"].startswith("/image?uri=")
+
+
+def test_mix_feed_falls_back_to_videos_when_no_images(tmp_path, monkeypatch):
+    media_root = tmp_path / "media"
+    media_root.mkdir(parents=True, exist_ok=True)
+    (media_root / "only-video.mp4").write_bytes(b"00")
+    (media_root / "only-video-2.mp4").write_bytes(b"00")
+
+    data_root = tmp_path / "tiklocal-data"
+    monkeypatch.setenv("MEDIA_ROOT", str(media_root))
+    monkeypatch.setenv("TIKLOCAL_INSTANCE", str(data_root))
+
+    app = create_app({"TESTING": True, "MEDIA_ROOT": media_root})
+    test_client = app.test_client()
+
+    res = test_client.get("/api/feed/mix?page=1&size=8&seed=fixed-seed")
+    assert res.status_code == 200
+    data = res.get_json()
+
+    items = data["items"]
+    assert len(items) > 0
+    assert all(item["type"] == "video" for item in items)
diff --git a/tiklocal/app.py b/tiklocal/app.py
diff --git a/tiklocal/static/output.css b/tiklocal/static/output.css
diff --git a/tiklocal/templates/tiktok.html b/tiklocal/templates/tiktok.html
