vidknot 0.1.0__tar.gz

vidknot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VidkNot Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vidknot-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: vidknot
+Version: 0.1.0
+Summary: VidkNot — Video Knowledge, Knotted. 一键将视频链接转换为结构化笔记，支持飞书、语雀、Notion、Obsidian 等多平台存储。
+Author: VidkNot Team
+License: MIT
+Project-URL: Homepage, https://github.com/suonian/vidknot
+Project-URL: Repository, https://github.com/suonian/vidknot
+Project-URL: Issues, https://github.com/suonian/vidknot/issues
+Keywords: video,transcription,AI,notes,knowledge-base,feishu,yuque,notion,obsidian,markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2026.3.17
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: openai>=1.0.0
+Provides-Extra: feishu
+Requires-Dist: feishu-docx>=0.1.0; extra == "feishu"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.2.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: feishu-docx>=0.1.0; extra == "all"
+Requires-Dist: pytest>=8.0.0; extra == "all"
+Requires-Dist: ruff>=0.2.0; extra == "all"
+Dynamic: license-file
+
+- 📖 [文档改进](https://github.com/suonian/vidknot/issues)

vidknot-0.1.0/README.md

@@ -0,0 +1 @@
+- 📖 [文档改进](https://github.com/suonian/vidknot/issues)

vidknot-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vidknot"
+version = "0.1.0"
+description = "VidkNot — Video Knowledge, Knotted. 一键将视频链接转换为结构化笔记，支持飞书、语雀、Notion、Obsidian 等多平台存储。"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "VidkNot Team"}]
+keywords = ["video", "transcription", "AI", "notes", "knowledge-base", "feishu", "yuque", "notion", "obsidian", "markdown"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "yt-dlp>=2026.3.17",
+    "fastapi>=0.136.0",
+    "uvicorn[standard]>=0.27.0",
+    "httpx>=0.27.0",
+    "pyyaml>=6.0.1",
+    "openai>=1.0.0",
+]
+
+[project.optional-dependencies]
+feishu = ["feishu-docx>=0.1.0"]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.2.0",
+]
+all = [
+    "feishu-docx>=0.1.0",
+    "pytest>=8.0.0",
+    "ruff>=0.2.0",
+]
+
+[project.scripts]
+vidknot = "vidknot.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/suonian/vidknot"
+Repository = "https://github.com/suonian/vidknot"
+Issues = "https://github.com/suonian/vidknot/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+vidknot = ["*.yaml", "*.yml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

vidknot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vidknot-0.1.0/src/vidknot/__init__.py

@@ -0,0 +1,25 @@
+"""
+VidkNot - Video Knowledge, Knotted.
+
+Tie your video knowledge together.
+视频知识，结成一网。
+
+Core module for Agent-driven video knowledge pipeline.
+"""
+
+__version__ = "0.1.0"
+__author__ = "VidkNot Team"
+__license__ = "MIT"
+
+from .core.downloader import VideoDownloader
+from .core.transcriber import SiliconFlowASR, get_transcriber
+from .core.processor import ContentProcessor
+from .pipeline.video_knowledge_pipeline import VideoKnowledgePipeline
+
+__all__ = [
+    "VideoDownloader",
+    "SiliconFlowASR",
+    "get_transcriber",
+    "ContentProcessor",
+    "VideoKnowledgePipeline",
+]

vidknot-0.1.0/src/vidknot/__main__.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""
+VidkNot 统一入口
+
+支持三种运行模式:
+- CLI: python -m vidknot <url> [--destination feishu|yuque|notion|obsidian|both|none]
+- MCP: python -m vidknot --mcp
+- FastAPI: uvicorn vidknot.api:app
+"""
+
+import sys
+import argparse
+from pathlib import Path
+
+from .utils.logger import get_logger
+
+logger = get_logger("vidknot.cli")
+
+
+def main():
+    """智能检测运行模式并启动对应服务"""
+    parser = argparse.ArgumentParser(
+        description="VidkNot — Video Knowledge, Knotted. 将视频链接转换为结构化笔记，自动保存到飞书文档或 Obsidian Vault。",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+运行模式:
+  CLI 模式:   python -m vidknot <url> [--destination feishu|yuque|notion|obsidian|both|none]
+  MCP 模式:   python -m vidknot --mcp
+  API 模式:   uvicorn vidknot.api:app --reload
+
+示例:
+  # 生成笔记并保存到 Obsidian (默认)
+  python -m vidknot https://youtube.com/watch?v=xxx
+
+  # 保存到飞书文档
+  python -m vidknot https://bilibili.com/video/BVxxx --destination feishu
+
+  # 仅返回笔记内容，不保存
+  python -m vidknot https://youtube.com/watch?v=xxx --destination none
+
+  # 启动 MCP Server (用于 OpenClaw / Claude Desktop)
+  python -m vidknot --mcp
+        """
+    )
+
+    # 运行模式参数
+    parser.add_argument("--mcp", action="store_true",
+                        help="启动 MCP Stdio 模式 (用于 OpenClaw / Claude Desktop)")
+    parser.add_argument("--cli", action="store_true",
+                        help="强制使用 CLI 模式 (默认自动检测)")
+    parser.add_argument("--check-env", action="store_true",
+                        help="检查运行环境依赖是否满足")
+
+    # CLI 参数
+    parser.add_argument("url", nargs="?",
+                        help="视频 URL (CLI 模式)")
+    parser.add_argument("--raw", action="store_true",
+                        help="仅输出原始转录文本")
+    parser.add_argument("--summary", action="store_true",
+                        help="生成结构化笔记 (默认)")
+    parser.add_argument("--destination", "-d", default="obsidian",
+                        choices=["feishu", "yuque", "notion", "obsidian", "both", "none"],
+                        help="笔记保存目的地: feishu(飞书)/yuque(语雀)/notion/obsidian(本地)/both(所有)/none(仅返回)")
+    parser.add_argument("--language", "-l", default="auto",
+                        help="视频语言: auto/zh/en/ja/ko (默认: auto)")
+    parser.add_argument("--output", "-o",
+                        help="输出文件路径 (当 destination=none 时)")
+    parser.add_argument("--no-cache", action="store_true",
+                        help="禁用缓存")
+    parser.add_argument("--feishu-folder",
+                        help="飞书文档保存的文件夹名称")
+    parser.add_argument("--obsidian-tags", nargs="+", default=[],
+                        help="Obsidian 笔记标签")
+    parser.add_argument("--notify", action="store_true", default=True,
+                        help="处理完成后发送通知 (通过 OpenClaw 消息回复)")
+
+    args = parser.parse_args()
+
+    # 模式检测优先级: check-env > MCP > CLI (有url) > Help
+    if args.check_env:
+        from .utils.env_check import check_all_requirements, get_install_guide
+        all_ok, messages = check_all_requirements()
+        for msg in messages:
+            print(msg)
+        if not all_ok:
+            print("\n" + get_install_guide())
+            sys.exit(1)
+        print("\n[OK] 所有环境检查通过")
+        sys.exit(0)
+
+    if args.mcp:
+        # MCP Stdio 模式
+        from .adapters.mcp_server import run_mcp_server
+        run_mcp_server()
+
+    elif args.url or args.cli:
+        # CLI 模式
+        if not args.url and args.cli:
+            parser.error("CLI 模式需要提供 URL 参数")
+        run_cli(args)
+
+    else:
+        # 检查是否通过 uvicorn 调用 (FastAPI 模式)
+        if "uvicorn" in sys.argv[0] or any("uvicorn" in arg for arg in sys.argv):
+            print("启动 FastAPI 模式，请访问 http://localhost:8000/docs")
+            return
+
+        parser.print_help()
+        sys.exit(1)
+
+
+def run_cli(args):
+    """CLI 模式主逻辑（同步）"""
+    from .core.downloader import VideoDownloader
+    from .core.transcriber import SiliconFlowASR
+    from .core.processor import ContentProcessor
+    from .utils.cache_manager import CacheManager
+    from .utils.env_check import check_ffmpeg, check_all_requirements
+    from .pipeline.video_knowledge_pipeline import VideoKnowledgePipeline
+
+    logger.info("VidkNot v0.1.0 — Video Knowledge, Knotted.")
+
+    # 环境检查
+    logger.info("检查运行环境...")
+    all_ok, messages = check_all_requirements()
+    if not all_ok:
+        for msg in messages:
+            if "❌" in msg:
+                logger.error(msg)
+        logger.error("请安装缺失的依赖后重试")
+        sys.exit(1)
+
+    ffmpeg_ok, ffmpeg_path = check_ffmpeg()
+    logger.info(f"FFmpeg: {ffmpeg_path}")
+
+    # 确定模式
+    mode = "raw" if args.raw else "summary"
+    destination = args.destination
+
+    url = args.url
+    logger.info(f"正在处理: {url}")
+    logger.info(f"处理模式: {'结构化笔记' if mode == 'summary' else '原始转录'}")
+    logger.info(f"目的地: {destination}")
+
+    # 检查缓存
+    cache = CacheManager()
+    if not args.no_cache:
+        cached = cache.get(url, mode)
+        if cached:
+            logger.info("命中缓存!")
+            result = cached
+        else:
+            result = process_video(url, mode, args.language)
+            cache.set(url, mode, result)
+    else:
+        result = process_video(url, mode, args.language)
+
+    # 根据目的地路由
+    if destination != "none":
+        pipeline = VideoKnowledgePipeline(
+            destination=destination,
+            format=mode,
+            language=args.language,
+        )
+        saved = pipeline.save(result, {
+            "feishu_folder": args.feishu_folder,
+            "obsidian_tags": args.obsidian_tags,
+        })
+        logger.info(f"已保存到: {saved}")
+
+    # 输出结果
+    if mode == "summary":
+        output = result.get("markdown", "")
+    else:
+        output = result.get("transcription", "")
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(output)
+        logger.info(f"结果已保存: {args.output}")
+    else:
+        print("\n" + "=" * 60)
+        print(output)
+        print("=" * 60)
+
+
+def generate_images_markdown(metadata: dict, image_paths: list) -> str:
+    """为纯图片内容生成 Markdown"""
+    from datetime import date
+
+    title = metadata.get("title", "小红书图片笔记")
+    url = metadata.get("url", "")
+    image_dir = metadata.get("image_paths", [])
+
+    lines = [
+        "---",
+        f"title: {title}",
+        f"source: {url}",
+        f"date: {date.today().isoformat()}",
+        f"platform: xiaohongshu",
+        f"type: images",
+        "---",
+        "",
+        f"# {title}",
+        "",
+        f"来源: {url}",
+        "",
+        f"图片数量: {len(image_paths)} 张",
+        "",
+        "## 图片列表",
+        "",
+    ]
+
+    for i, img_path in enumerate(image_paths, 1):
+        from pathlib import Path
+        filename = Path(img_path).name
+        lines.append(f"### 图片 {i}")
+        lines.append(f"![图片 {i}]({filename})")
+        lines.append("")
+
+    lines.append("---")
+    lines.append(f"*图片保存目录: {image_dir[0].rsplit('/', 1)[0] if image_dir else '未知'}*")
+
+    return "\n".join(lines)
+
+
+def process_video(url: str, mode: str, language: str) -> dict:
+    """处理视频的完整流程（同步）"""
+    from .core.downloader import VideoDownloader
+    from .core.transcriber import SiliconFlowASR
+    from .core.processor import ContentProcessor
+
+    logger.info("正在下载...")
+    downloader = VideoDownloader()
+    file_path, metadata = downloader.download_audio_with_metadata(url)
+    logger.info(f"下载完成: {metadata.get('title', 'Unknown')}")
+
+    result = {
+        "title": metadata.get("title"),
+        "author": metadata.get("uploader"),
+        "duration": metadata.get("duration"),
+        "source_url": url,
+        "transcription": "",
+        "metadata": metadata,
+    }
+
+    if metadata.get("is_images_only"):
+        image_count = metadata.get("image_count", 0)
+        image_paths = metadata.get("image_paths", [])
+        result["transcription"] = ""
+        result["markdown"] = generate_images_markdown(metadata, image_paths)
+        result["is_images_only"] = True
+        logger.info(f"纯图片笔记: {image_count} 张图片")
+        return result
+
+    logger.info("正在转录...")
+    transcriber = SiliconFlowASR()
+    transcription = transcriber.transcribe(file_path, language=language)
+    logger.info(f"转录完成: {len(transcription)} 字符")
+    result["transcription"] = transcription
+
+    if mode == "summary":
+        logger.info("正在生成结构化笔记...")
+        processor = ContentProcessor()
+        processed = processor.summarize(transcription, metadata)
+        result["markdown"] = processed["markdown"]
+        logger.info("笔记生成完成")
+    else:
+        result["markdown"] = transcription
+
+    return result
+
+
+if __name__ == "__main__":
+    main()

vidknot-0.1.0/src/vidknot/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""
+VidkNot 适配器模块
+"""
+
+from .mcp_server import MCPServer, run_mcp_server
+from .agent_bridge import get_tool_metadata, execute_tool
+
+__all__ = [
+    "MCPServer",
+    "run_mcp_server",
+    "get_tool_metadata",
+    "execute_tool",
+]

vidknot-0.1.0/src/vidknot/adapters/agent_bridge.py

@@ -0,0 +1,147 @@
+"""
+VidkNot Agent 桥接模块
+
+提供 OpenAI Function Calling Schema 定义
+用于 OpenAI / Claude 等 AI Agent 集成
+"""
+
+import asyncio
+import json
+from typing import Dict, Any, Optional
+
+
+def get_tool_metadata() -> Dict[str, Any]:
+    """
+    获取 VidkNot 工具的 OpenAI Function Calling Schema
+
+    Returns:
+        OpenAI tool schema dict
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": "video_knowledge",
+            "description": """将视频链接转换为结构化笔记，并自动保存到飞书文档或 Obsidian Vault。
+
+适用于以下场景：
+- 用户转发视频链接后，AI Agent 自动生成学习笔记
+- 将视频内容整理为可搜索的 Markdown 笔记
+- 自动提取视频要点、章节、关键信息
+
+支持的平台：YouTube、Bilibili、抖音、小红书、微博、Twitter/X 等 20+ 平台
+
+输出：结构化的 Markdown 笔记，包含 YAML Frontmatter（标题、作者、时长、标签等）""",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "url": {
+                        "type": "string",
+                        "description": "视频链接，支持 YouTube、Bilibili、抖音、小红书、微博、Twitter/X 等平台"
+                    },
+                    "destination": {
+                        "type": "string",
+                        "enum": ["feishu", "obsidian", "both", "none"],
+                        "description": "笔记保存目的地：feishu=飞书云文档，obsidian=本地 Obsidian Vault，both=两者同时，none=仅返回内容",
+                        "default": "obsidian"
+                    },
+                    "format": {
+                        "type": "string",
+                        "enum": ["structured", "raw"],
+                        "description": "structured=结构化笔记（含要点、详细内容、标签），raw=仅原始转录",
+                        "default": "structured"
+                    },
+                    "language": {
+                        "type": "string",
+                        "description": "视频语言：auto（自动检测）/ zh / en / ja / ko",
+                        "default": "auto"
+                    },
+                    "feishu_folder": {
+                        "type": "string",
+                        "description": "飞书文档保存的文件夹名称（如：视频笔记、学习资料）"
+                    },
+                    "obsidian_tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Obsidian 笔记标签（自动添加到 YAML Frontmatter 的 tags 字段）"
+                    },
+                    "notify": {
+                        "type": "boolean",
+                        "description": "处理完成后是否发送通知（通过 Agent 消息回复用户）",
+                        "default": True
+                    }
+                },
+                "required": ["url"]
+            }
+        }
+    }
+
+
+def execute_tool(arguments: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    执行 video_knowledge 工具
+
+    Args:
+        arguments: 工具参数
+
+    Returns:
+        工具执行结果
+    """
+    from ..pipeline.video_knowledge_pipeline import VideoKnowledgePipeline
+
+    url = arguments.get("url")
+    destination = arguments.get("destination", "obsidian")
+    format_mode = arguments.get("format", "structured")
+    language = arguments.get("language", "auto")
+    feishu_folder = arguments.get("feishu_folder")
+    obsidian_tags = arguments.get("obsidian_tags", [])
+    notify = arguments.get("notify", True)
+
+    if not url:
+        return {
+            "success": False,
+            "error": "URL is required"
+        }
+
+    try:
+        pipeline = VideoKnowledgePipeline(
+            destination=destination,
+            format=format_mode,
+            language=language,
+        )
+
+        result = asyncio.run(pipeline.run(url))
+
+        if destination != "none":
+            saved = asyncio.run(
+                pipeline.save(result, {
+                    "feishu_folder": feishu_folder,
+                    "obsidian_tags": obsidian_tags,
+                })
+            )
+            result["saved_to"] = saved
+
+        if notify:
+            dest_label = {
+                "feishu": "飞书文档",
+                "obsidian": "Obsidian Vault",
+                "both": "飞书文档和 Obsidian",
+            }.get(destination, destination)
+            result["notify_message"] = f"✅ 笔记已生成并保存到 {dest_label}！"
+
+        return result
+
+    except Exception as e:
+        # 分类异常，返回结构化错误
+        from ..utils.exceptions import VidkNotError
+        if isinstance(e, VidkNotError):
+            return {
+                "success": False,
+                "error": e.message,
+                "error_details": e.details,
+                "error_type": e.__class__.__name__,
+            }
+        return {
+            "success": False,
+            "error": str(e),
+            "error_type": e.__class__.__name__,
+        }