release: v0.8.7 来源回跳与结构化命名

Author: ChanMo

docs/release_notes.md

@@ -1,5 +1,13 @@
 # Release Notes
 
+## v0.8.7 (2026-02-21)
+- 新增“来源回跳”能力：下载成功后将文件与原始 URL 建立映射，并新增 `~/.tiklocal/download_sources.json` 持久化来源索引。
+- 新增来源解析三层兜底：优先来源映射，其次 `.info.json`（`webpage_url/original_url`），最后按文件名结构推断平台链接（x/youtube/tiktok/instagram）。
+- 新增来源查询 API：`GET /api/source` 与 `POST /api/source/batch`，用于详情页与下载列表按文件获取来源信息。
+- 视频/图片详情页“操作”区新增“查看来源”入口；下载列表输出文件旁新增来源链接展示。
+- `yt-dlp` 输出命名升级为结构化短名，并启用 `--write-info-json` 以增强跨平台回跳恢复能力。
+- 新增来源相关测试覆盖：来源映射写入、历史清理保留、info.json/文件名回退、批量查询与删除文件同步清理映射。
+
 ## v0.8.6 (2026-02-21)
 - URL 下载中心升级为双引擎：支持按任务手动选择 `yt-dlp` / `gallery-dl`，并在运行状态中展示双引擎可用性与版本。
 - 下载任务模型增强：新增 `engine`、`engine_version`、`output_files_rel`、`file_count` 字段；兼容旧任务历史记录恢复。

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "tiklocal",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "description": "A local media server that combines the features of TikTok and Pinterest",
   "scripts": {
     "build-css": "tailwindcss -i ./tiklocal/static/input.css -o ./tiklocal/static/output.css --watch",

package.json

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "TikLocal"
-version = "0.8.6"
+version = "0.8.7"
 description = "A local media server that combines the features of TikTok and Pinterest"
 authors = ["ChanMo <chan.mo@outlook.com>"]
 readme = "README.md"

pyproject.toml

@@ -276,3 +276,103 @@ def test_delete_and_clear_history(client):
     assert clear_res.status_code == 200
     assert clear_data["success"] is True
     assert clear_data["data"]["deleted"] >= 0
+
+
+def test_source_api_from_job_map(client):
+    res = client.post("/api/download/jobs", json={"url": "https://x.com/i/web/status/1234567890123456789?utm_source=test"})
+    data = res.get_json()
+    assert res.status_code == 200
+    job_id = data["data"]["job"]["id"]
+    _wait_for_job(client, job_id)
+
+    source_res = client.get("/api/source", query_string={"file": "mock-output.mp4"})
+    source_data = source_res.get_json()
+    assert source_res.status_code == 200
+    assert source_data["success"] is True
+    assert source_data["data"]["source"]["resolved_by"] == "map"
+    assert source_data["data"]["source"]["source_domain"] == "x.com"
+    assert source_data["data"]["source"]["source_url_display"] == "https://x.com/i/web/status/1234567890123456789"
+
+
+def test_source_map_kept_after_clear_history(client):
+    res = client.post("/api/download/jobs", json={"url": "https://example.com/keep-source"})
+    job_id = res.get_json()["data"]["job"]["id"]
+    _wait_for_job(client, job_id)
+
+    clear_res = client.post("/api/download/jobs/clear")
+    assert clear_res.status_code == 200
+
+    source_res = client.get("/api/source", query_string={"file": "mock-output.mp4"})
+    source_data = source_res.get_json()
+    assert source_res.status_code == 200
+    assert source_data["success"] is True
+    assert source_data["data"]["source"]["source_url_raw"] == "https://example.com/keep-source"
+
+
+def test_source_resolve_from_info_json(client):
+    media_root = client.application.config["MEDIA_ROOT"]
+    media_file = media_root / "fallback-info.mp4"
+    media_file.write_bytes(b"00")
+    info_file = media_root / "fallback-info.info.json"
+    info_file.write_text(
+        '{"webpage_url":"https://www.youtube.com/watch?v=abc123&utm_source=mail"}',
+        encoding="utf-8",
+    )
+
+    source_res = client.get("/api/source", query_string={"file": "fallback-info.mp4"})
+    source_data = source_res.get_json()
+    assert source_res.status_code == 200
+    assert source_data["success"] is True
+    assert source_data["data"]["source"]["resolved_by"] == "infojson"
+    assert source_data["data"]["source"]["source_url_display"] == "https://www.youtube.com/watch?v=abc123"
+    assert source_data["data"]["source"]["source_domain"] == "www.youtube.com"
+
+
+def test_source_resolve_from_filename(client):
+    media_root = client.application.config["MEDIA_ROOT"]
+    name = "twitter__alice__189111222333444555__189111222333444555__20260221__01.mp4"
+    (media_root / name).write_bytes(b"00")
+
+    source_res = client.get("/api/source", query_string={"file": name})
+    source_data = source_res.get_json()
+    assert source_res.status_code == 200
+    assert source_data["success"] is True
+    assert source_data["data"]["source"]["resolved_by"] == "filename"
+    assert source_data["data"]["source"]["source_url_display"] == "https://x.com/alice/status/189111222333444555"
+    assert source_data["data"]["source"]["source_domain"] == "x.com"
+
+
+def test_source_batch_api(client):
+    media_root = client.application.config["MEDIA_ROOT"]
+    media_file = media_root / "batch-fallback.mp4"
+    media_file.write_bytes(b"00")
+    (media_root / "batch-fallback.info.json").write_text(
+        '{"webpage_url":"https://www.tiktok.com/@u/video/12345"}',
+        encoding="utf-8",
+    )
+
+    res = client.post("/api/source/batch", json={"files": ["batch-fallback.mp4", "missing.mp4"]})
+    data = res.get_json()
+    assert res.status_code == 200
+    assert data["success"] is True
+    assert data["data"]["items"]["batch-fallback.mp4"]["source_domain"] == "www.tiktok.com"
+    assert data["data"]["items"]["missing.mp4"] is None
+
+
+def test_delete_file_also_deletes_source_map(client):
+    media_root = client.application.config["MEDIA_ROOT"]
+    media_file = media_root / "mock-output.mp4"
+    media_file.write_bytes(b"00")
+
+    res = client.post("/api/download/jobs", json={"url": "https://example.com/delete-source"})
+    job_id = res.get_json()["data"]["job"]["id"]
+    _wait_for_job(client, job_id)
+
+    delete_res = client.post("/delete/mock-output.mp4", follow_redirects=False)
+    assert delete_res.status_code in {301, 302, 303, 307, 308}
+
+    source_res = client.get("/api/source", query_string={"file": "mock-output.mp4"})
+    source_data = source_res.get_json()
+    assert source_res.status_code == 200
+    assert source_data["success"] is True
+    assert source_data["data"]["source"] is None

tests/test_download.py

@@ -29,6 +29,7 @@
     DEFAULT_DOWNLOAD_CONFIG,
     DownloadConfigStore,
     DownloadHistoryStore,
+    DownloadSourceStore,
     DownloadManager,
     validate_download_config,
     validate_download_url,
@@ -39,6 +40,7 @@
     get_llm_config_path,
     get_download_config_path,
     get_download_jobs_path,
+    get_download_sources_path,
 )
 
 
@@ -98,10 +100,12 @@ def create_app(test_config=None):
     llm_config_store = LLMConfigStore(get_llm_config_path())
     download_config_store = DownloadConfigStore(get_download_config_path())
     download_history_store = DownloadHistoryStore(get_download_jobs_path())
+    download_source_store = DownloadSourceStore(get_download_sources_path())
     download_manager = DownloadManager(
         Path(media_root_str),
         download_config_store,
         download_history_store,
+        source_store=download_source_store,
     )
 
     def build_prompt_config_payload(custom_config=None):
@@ -290,6 +294,7 @@ def detail_view(name):
 
         if target.suffix.lower() in IMAGE_EXTENSIONS:
             return redirect(f"/image?uri={quote(name)}")
+        source_meta = download_manager.resolve_source_for_file(name)
 
         # Context navigation (prev/next)
         # Note: Re-scanning every request is inefficient for large libraries, 
@@ -310,7 +315,8 @@ def detail_view(name):
             mtime=datetime.datetime.fromtimestamp(target.stat().st_mtime).strftime('%Y-%m-%d %H:%M'),
             size=target.stat().st_size,
             previous_item=prev_item,
-            next_item=next_item
+            next_item=next_item,
+            source_meta=source_meta,
         )
 
     @app.route('/image')
@@ -320,8 +326,8 @@ def image_view():
 
         target = library_service.resolve_path(uri)
         if not target or not target.exists(): return "File not found", 404
-        
-        return render_template('image_detail.html', image=target, uri=uri, stat=target.stat())
+        source_meta = download_manager.resolve_source_for_file(uri)
+        return render_template('image_detail.html', image=target, uri=uri, stat=target.stat(), source_meta=source_meta)
 
     @app.route("/delete/<path:name>", methods=['POST', 'GET'])
     def delete_view(name):
@@ -330,6 +336,7 @@ def delete_view(name):
             if target and target.exists():
                 try:
                     target.unlink()
+                    download_manager.delete_source_for_file(name)
                     # Thumbnails are handled by OS or periodic cleanup, but ideally Service should handle it
                 except Exception as e:
                     return f"Error deleting file: {e}", 500
@@ -516,6 +523,31 @@ def api_download_job_retry(job_id):
             return {'success': False, 'error': error}, status
         return {'success': True, 'data': {'job': job}}
 
+    @app.route('/api/source')
+    def api_source_single():
+        file_rel = str(request.args.get('file', '')).strip()
+        if not file_rel:
+            return {'success': False, 'error': 'file 不能为空。'}, 400
+        source = download_manager.resolve_source_for_file(file_rel)
+        return {'success': True, 'data': {'file': file_rel, 'source': source}}
+
+    @app.route('/api/source/batch', methods=['POST'])
+    def api_source_batch():
+        payload = request.get_json(silent=True) or {}
+        files = payload.get('files')
+        if not isinstance(files, list):
+            return {'success': False, 'error': 'files 必须是数组。'}, 400
+
+        normalized: list[str] = []
+        for item in files:
+            value = str(item or '').strip()
+            if value:
+                normalized.append(value)
+            if len(normalized) >= 200:
+                break
+        items = download_manager.resolve_sources_for_files(normalized)
+        return {'success': True, 'data': {'items': items}}
+
     @app.route('/api/ai/prompt-config', methods=['GET', 'POST'])
     def api_prompt_config():
         if request.method == 'GET':

tiklocal/app.py

@@ -43,3 +43,7 @@ def get_download_config_path() -> Path:
 
 def get_download_jobs_path() -> Path:
     return get_data_dir() / 'download_jobs.json'
+
+
+def get_download_sources_path() -> Path:
+    return get_data_dir() / 'download_sources.json'