videonote 0.1.7__tar.gz

videonote-0.1.7/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "videonote",
+  "description": "VideoNote-Mcp：把视频链接变成 AI Markdown 笔记（Skill + MCP server），无需启动后端",
+  "owner": {
+    "name": "HuangYincan",
+    "url": "https://github.com/HuangYincan"
+  },
+  "plugins": [
+    {
+      "name": "videonote",
+      "source": "./",
+      "description": "生成视频笔记的 Skill 与 MCP server（下载→转写→LLM→Markdown）",
+      "displayName": "VideoNote",
+      "skills": ["./skills/videonote"]
+    }
+  ]
+}

videonote-0.1.7/.claude-plugin/plugin.json

@@ -0,0 +1,122 @@
+{
+  "name": "videonote",
+  "version": "0.1.7",
+  "description": "Generate AI Markdown notes from video links (Bilibili/YouTube/Douyin/Kuaishou/local)",
+  "author": {
+    "name": "HuangYincan",
+    "url": "https://github.com/HuangYincan"
+  },
+  "commands": [
+    "./commands/"
+  ],
+  "mcpServers": {
+    "videonote": {
+      "command": "uvx",
+      "args": [
+        "videonote"
+      ],
+      "env": {
+        "VIDEONOTE_DEFAULT_STYLE": "${user_config.default_style}",
+        "VIDEONOTE_DEFAULT_SCREENSHOT": "${user_config.default_screenshot}",
+        "VIDEONOTE_VIDEO_UNDERSTANDING": "${user_config.video_understanding}",
+        "VIDEONOTE_INCLUDE_COMMENTS": "${user_config.include_comments}",
+        "VIDEONOTE_NOTES_DIR": "${user_config.notes_dir}",
+        "TRANSCRIBER_TYPE": "${user_config.transcriber_type}",
+        "WHISPER_MODEL_SIZE": "${user_config.whisper_model_size}",
+        "VIDEONOTE_VIDEO_INTERVAL": "${user_config.video_interval}",
+        "VIDEONOTE_COMMENTS_LIMIT": "${user_config.comments_limit}",
+        "VIDEONOTE_DEFAULT_EXPORT_FORMATS": "${user_config.default_export_formats}",
+        "VIDEONOTE_ENABLE_PREPROCESS": "${user_config.enable_preprocess}",
+        "VIDEONOTE_DIARIZATION": "${user_config.diarization}",
+        "VIDEONOTE_MAX_WORKERS": "${user_config.max_workers}",
+        "VIDEONOTE_STDERR_LOG_MAX_MB": "${user_config.stderr_log_max_mb}"
+      }
+    }
+  },
+  "userConfig": {
+    "default_style": {
+      "type": "string",
+      "title": "笔记风格默认",
+      "description": "直接输入英文 key，其一：detailed 详细 / minimal 精简 / academic 学术 / tutorial 教程 / xiaohongshu 小红书 / life_journal 生活向 / task_oriented 任务导向 / business 商业 / meeting_minutes 会议纪要",
+      "default": "detailed"
+    },
+    "default_screenshot": {
+      "type": "boolean",
+      "title": "笔记默认插图",
+      "description": "输入 true 或 false。true=生成笔记时默认插入视频截图",
+      "default": false
+    },
+    "video_understanding": {
+      "type": "boolean",
+      "title": "视频理解默认",
+      "description": "输入 true 或 false。true=默认把画面抽帧发给多模态 LLM（需多模态模型）",
+      "default": false
+    },
+    "include_comments": {
+      "type": "boolean",
+      "title": "弹幕+评论整合默认",
+      "description": "输入 true 或 false。true=默认把 B 站弹幕+热门评论整合进笔记（需 SESSDATA）",
+      "default": false
+    },
+    "notes_dir": {
+      "type": "directory",
+      "title": "笔记默认位置",
+      "description": "输入笔记输出目录的绝对路径。留空=默认 note_results/{task_id}/",
+      "default": ""
+    },
+    "transcriber_type": {
+      "type": "string",
+      "title": "语音转写引擎",
+      "description": "直接输入英文 key，其一：fast-whisper 本地（推荐，免费）/ funasr 本地（中文更优，需手动切换）/ groq 云端 / bcut 云端 / kuaishou 云端 / mlx-whisper 本地（macOS）",
+      "default": "fast-whisper"
+    },
+    "whisper_model_size": {
+      "type": "string",
+      "title": "Whisper 模型尺寸",
+      "description": "直接输入英文 key，其一：tiny / base / small / medium / large-v3 / large-v3-turbo（内存小用 tiny/base，追求精度用 medium+；中文建议 small 起）",
+      "default": "small"
+    },
+    "video_interval": {
+      "type": "number",
+      "title": "视频理解截帧间隔（秒）",
+      "description": "数字，如 6。默认关闭时无效；开视频理解时每 N 秒抽一帧",
+      "default": 6
+    },
+    "comments_limit": {
+      "type": "number",
+      "title": "弹幕+评论条数上限",
+      "description": "数字，默认 20。开弹幕/评论整合时抓取的条数",
+      "default": 20
+    },
+    "default_export_formats": {
+      "type": "string",
+      "title": "转写导出格式默认",
+      "description": "JSON 数组字符串，如 [\"srt\",\"vtt\"]。留空=不自动导出（成功后可手动 export_transcript）",
+      "default": ""
+    },
+    "enable_preprocess": {
+      "type": "boolean",
+      "title": "音频预处理",
+      "description": "输入 true 或 false。true=转写前做 16kHz 归一化+超长分块（提高长视频转写稳定）",
+      "default": false
+    },
+    "diarization": {
+      "type": "boolean",
+      "title": "说话人分离",
+      "description": "输入 true 或 false。true=转写后做说话人分离（需可选依赖 pyannote，且需要 HF token）",
+      "default": false
+    },
+    "max_workers": {
+      "type": "number",
+      "title": "并发任务上限",
+      "description": "数字，默认 3。同时执行的笔记生成任务数上限（排队不算；机器强可调大，弱可调小）",
+      "default": 3
+    },
+    "stderr_log_max_mb": {
+      "type": "number",
+      "title": "MCP 日志轮转上限（MB）",
+      "description": "数字，默认 50。mcp_stderr.log 超过该大小后轮转为 .log.1",
+      "default": 50
+    }
+  }
+}

videonote-0.1.7/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.venv
+data
+models
+note_results
+config
+logs
+dist
+build
+*.db
+*.pyc
+__pycache__
+.github

videonote-0.1.7/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+
+jobs:
+  smoke:
+    name: Smoke test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - name: Install dependencies (Python ${{ matrix.python-version }})
+        run: |
+          uv python install ${{ matrix.python-version }}
+          uv sync --frozen --python ${{ matrix.python-version }}
+      - name: Ruff F-class lint
+        run: uv run ruff check --select F .
+      - name: Server imports
+        run: uv run python -c "import videonote_mcp.server; print('import OK')"
+      - name: MCP tools/list over stdio
+        run: |
+          uv run python - <<'EOF'
+          import asyncio
+          from mcp import ClientSession, StdioServerParameters
+          from mcp.client.stdio import stdio_client
+
+          async def main():
+              params = StdioServerParameters(command="uv", args=["run", "videonote"])
+              async with stdio_client(params) as (read, write):
+                  async with ClientSession(read, write) as session:
+                      await session.initialize()
+                      tools = await session.list_tools()
+                      names = sorted(t.name for t in tools.tools)
+                      # 名单断言（docs/05 #70）：数量断言放过名字漂移（get_task_status 曾
+                      # 丢失装饰器仍 38 全绿），必须精确匹配。改名/增删工具时同步这里。
+                      expected = [
+                          "batch_generate_notes", "cancel_note", "cleanup_all", "cleanup_note",
+                          "diarize_media", "export_transcript", "generate_note", "get_config",
+                          "get_task_status", "get_task_transcript", "health_check",
+                          "inspect_video", "list_tasks", "merge_audio", "preflight",
+                          "prepare_note_material",
+                      ]
+                      assert names == expected, f"工具名单漂移: {names}"
+                      print(f"tools/list OK: {len(names)} tools (名单精确匹配)")
+          asyncio.run(main())
+          EOF
+      - name: CLI smoke
+        run: uv run videonote providers list
+      - name: Unit tests
+        run: uv run pytest -q
+
+  # 汇总 job：main 分支保护规则要求 context "Smoke test"（矩阵 job 名带
+  # Python 版本，规则早于矩阵化配置）。needs 矩阵全部通过才绿，
+  # 任一失败即失败（fail-fast: false 保证三个版本都跑完）。
+  smoke-summary:
+    name: Smoke test
+    needs: smoke
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Smoke tests passed (Python 3.11/3.12/3.13)"

videonote-0.1.7/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  test:
+    name: Test gate (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - name: Install dependencies (Python ${{ matrix.python-version }})
+        run: |
+          uv python install ${{ matrix.python-version }}
+          uv sync --frozen --python ${{ matrix.python-version }}
+      - name: Ruff F-class lint
+        run: uv run ruff check --select F .
+      - name: Unit tests
+        run: uv run pytest -q
+
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      # uv 不在 runner 默认 PATH（CI job 有 setup-uv，release job 漏了）——
+      # `uv build` command not found（exit 127）致 v0.1.6 首次发布失败
+      - uses: astral-sh/setup-uv@v7
+      - name: Verify version matches tag
+        run: |
+          pkg_version="$(grep -m1 '^version' pyproject.toml | sed -E 's/version = "([^"]+)"/\1/')"
+          init_version="$(grep -m1 '__version__' videonote_mcp/__init__.py | sed -E 's/__version__ = "([^"]+)"/\1/')"
+          plugin_version="$(grep -m1 '"version"' .claude-plugin/plugin.json | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"
+          tag_version="${GITHUB_REF_NAME#v}"
+          echo "pyproject version:      $pkg_version"
+          echo "__init__ version:       $init_version"
+          echo "plugin.json version:    $plugin_version"
+          echo "tag version:            $tag_version"
+          if [ "$pkg_version" != "$tag_version" ] || [ "$init_version" != "$tag_version" ] || [ "$plugin_version" != "$tag_version" ]; then
+            echo "::error::版本不一致（pyproject=$pkg_version / __init__=$init_version / plugin=$plugin_version / tag=${GITHUB_REF_NAME}），拒绝发布"
+            exit 1
+          fi
+          echo "✅ 四处版本一致，继续发布"
+      - name: Build wheel and verify contents
+        run: |
+          uv build --no-sources
+          wheel="$(ls dist/*.whl | head -1)"
+          echo "wheel: $wheel"
+          python - <<EOF
+          import zipfile, glob, sys
+          wheel = glob.glob("dist/*.whl")[0]
+          with zipfile.ZipFile(wheel) as z:
+              names = z.namelist()
+          required = [
+              "videonote_mcp/server.py",
+              "app/services/note.py",
+              "app/services/constant.py",
+              "skills/videonote/SKILL.md",
+              "skills/videonote/reference/tools.md",
+          ]
+          missing = [r for r in required if not any(n.endswith(r) for n in names)]
+          if missing:
+              print("::error::wheel 缺少文件: %s" % missing)
+              sys.exit(1)
+          print("✅ wheel 内容完整（%d 个文件）" % len(names))
+          EOF
+      - name: Create release for tag
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release
+    permissions:
+      # Trusted publishing（OIDC）：GitHub Actions 直接以 PyPI 项目身份发布，
+      # 无需 API token 进仓库。前置：PyPI 项目 videonote 的 Publishing 里
+      # 添加 trusted publisher（owner=HuangYincan，repo=VideoNote-MCP，workflow=release.yml）。
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - name: Build wheel and sdist
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish

videonote-0.1.7/.gitignore

@@ -0,0 +1,44 @@
+# 运行时数据（根锚定，避免误伤 app/db/models 等源码目录）
+/data/
+/models/
+/note_results/
+/config/
+
+# 数据库
+*.db
+*.sqlite3
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# uv
+.uv/
+
+# 编辑器 / 系统
+.DS_Store
+.idea/
+.vscode/
+*.log
+
+# Claude Code 机器本地配置（插件/marketplace 安装状态，不入库）
+.claude/settings.json
+.claude/settings.local.json
+# 项目 CLAUDE.md（本机开发上下文，不提交）
+/CLAUDE.md
+# 项目开发专用 skills（只在本机开发用，不随插件分发/入库）
+.claude/skills/
+
+# LaTeX 编译产物（模板预览 main.pdf 除外，需入库）
+*.aux
+*.fdb_latexmk
+*.fls
+*.out
+*.synctex.gz

videonote-0.1.7/.python-version

@@ -0,0 +1 @@
+3.12

videonote-0.1.7/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## 开发流程
+
+- **功能分支（日常开发）**：每次改动都**从 `dev` 新建分支**，开发完成后 **PR 合并回 `dev`**（CI 必须绿）。命名规则（`描述` 用 kebab-case，如 `feat/mcp-tools`）：
+
+  | 前缀 | 用途 |
+  |------|------|
+  | `feat/` | 新功能 |
+  | `fix/` | 修复 |
+  | `docs/` | 文档 |
+  | `refactor/` | 重构 |
+  | `chore/` | 杂项（CI / 依赖 / 构建） |
+
+  示例：`git checkout -b feat/video-understanding dev`
+- **`dev`（集成分支，无保护）**：功能分支合并到这里；保持可跑，CI 每次 push 自动冒烟。
+- **发布分支 `main`（受保护）**：`main` 只接受 PR 合入 —— PR 必须 **Smoke test** 通过 + 1 个 approval；直接 push 会被拒（admin 也不例外）。
+- **发版**：`dev` 稳定后开 PR `dev → main`，合并后打 `git tag vX.Y.Z && git push origin vX.Y.Z` —— [Release workflow](.github/workflows/release.yml) 会自动创建 GitHub Release。
+
+## 本地开发
+
+```bash
+uv sync --no-dev --frozen   # 安装依赖（含本项目）
+uv run videonote setup   # 配置 LLM / 转写
+```
+
+## 冒烟测试（CI）
+
+```bash
+uv run python -c "import videonote_mcp.server; print('import OK')"
+# MCP tools/list over stdio（脚本见 .github/workflows/ci.yml）
+```
+
+## 提交前自查
+
+- `uv sync --frozen` 能过（锁文件与依赖一致）
+- `import videonote_mcp.server` 不报错
+- `uv run videonote providers list` 正常输出

videonote-0.1.7/Dockerfile

@@ -0,0 +1,32 @@
+# VideoNote-Mcp —— MCP server（stdio）
+# 用途：Docker 部署 / Glama (glama.ai/mcp/servers) 校验（提交时把本文件内容粘到 Glama 的 Dockerfile 栏）
+# 启动：无参数运行 = MCP stdio server（客户端 attach stdin/stdout）
+FROM python:3.12-slim
+
+# FFmpeg（音频/视频处理必需）
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# 安装 uv
+RUN pip install --no-cache-dir uv
+
+# 复制项目（源码必须与依赖一起就位，uv sync 会构建并安装本包，wheel 含 app/**）
+COPY pyproject.toml uv.lock README.md ./
+COPY videonote_mcp/ videonote_mcp/
+COPY app/ app/
+
+# 按锁文件安装依赖 + 本项目（--no-dev：不带可选依赖）
+RUN uv sync --no-dev --frozen
+
+# 非 root 运行（docs/05 第 16 轮 A3）：SSRF/文件写等被利用时容器内不放大到 root。
+# 数据目录随 HOME（/home/videonote/.local/share/videonote-mcp）走，/app 交给用户写。
+RUN useradd --create-home --uid 1000 videonote \
+    && chown -R videonote:videonote /app
+
+USER videonote
+ENV HOME=/home/videonote
+
+# MCP server（无参数 = stdio 模式）
+CMD ["uv", "run", "videonote"]

videonote-0.1.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yincan Huang
+
+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.