# install-by2kb

Adopt this skill: https://proskills.md/skills/other/charlesmpc-by2kb-by2kb-integrations-hermes-skills-install-by2kb

Page: https://proskills.md/skills/other/charlesmpc-by2kb-by2kb-integrations-hermes-skills-install-by2kb
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: by2kb/integrations/hermes/skills/install-by2kb/SKILL.md
size: 4010
upstream: https://github.com/charlesmpc/by2kb/blob/main/by2kb/integrations/hermes/skills/install-by2kb/SKILL.md

````text
---
name: install-by2kb
description: Install, configure, update, or diagnose the by2kb CLI for this Hermes plugin. Preserve existing configuration and keep Hermes-managed plugin code separate from CLI upgrades.
---

# Set up by2kb for Hermes

This plugin is already installed. Set up its separate CLI on the same machine and
under the same user as the Hermes gateway. Do not copy or replace the plugin, clone
the repository, or run `by2kb agent install hermes` from this workflow.

## Inspect first

- Check `by2kb version`, Python 3.12+, `ffmpeg`, `ffprobe`, and the available package
  manager. This plugin's staged request-file workflow requires by2kb 0.5.3 or newer;
  do not assume an arbitrary future version is compatible without checking its release notes.
- Check whether by2kb was installed with `pipx list` or `uv tool list`; use that
  manager for upgrades. Do not create a second installation with another manager.
- A missing command can be a PATH problem. On Windows use `Get-Command` and inspect
  `uv tool dir --bin` or `py -m pipx environment` when applicable. The gateway may
  need a restart to inherit a repaired PATH. `BY2KB_COMMAND` may name an absolute
  executable path (not a shell command with arguments).
- Treat `BY2KB_HOME` (default `~/.by2kb`), its `.env`, database, models, custom Skills,
  and the knowledge-base directory as user-owned. Do not display secret values.
- If configuration already exists, run `by2kb doctor --json` and repair only the
  reported problems. Do not run init or change providers just to make checks pass.

## First installation

Explain the dependencies and obtain agreement before installing. Prefer an already
available package manager; either of these installs an isolated CLI, not into Hermes:

```bash
pipx install "by2kb[asr-whisper,youtube]" --python 3.12
# Or, if uv is the chosen manager:
uv tool install --python 3.12 "by2kb[asr-whisper,youtube]"
```

Install ffmpeg/ffprobe using the platform's trusted package manager if missing.
Confirm the knowledge-base location, then, only for a new configuration:

```bash
by2kb init --preset agent-local --library-root "<chosen directory>"
```

Default to local Whisper and agent-hosted summaries; no separate LLM key or TOS
account is needed. Before `by2kb models install`, inspect `by2kb models status`,
explain the selected model and expected download size from its model information,
and obtain agreement. If the size cannot be established, say so rather than inventing it.
Then run `by2kb doctor --json` and explain remaining failures.

Cloud ASR is optional. If the user chooses Doubao, install the `asr-doubao,youtube`
extras using the same package manager and have them run `by2kb init` in a trusted
local terminal to configure TOS and ASR. Do not request secrets in chat. Preserve
existing configuration; changing an existing provider is a separate explicit choice.
The browser fallback is also optional: do not install Playwright or Chromium unless
the user chooses it. Follow the project's browser setup guide for that route.

## Finish and upgrade

- Enable the plugin with `hermes plugins enable by2kb` if needed. Ask before
  restarting an active gateway. Verify the gateway sees the CLI, then ask the user
  to send a test video URL. Do not claim success from installation alone.
- Upgrade the CLI with its existing manager: `pipx upgrade by2kb` or
  `uv tool upgrade by2kb`. Never run init with `--force` during an upgrade.
- For catalog-installed plugin code, use `hermes plugins update by2kb`. For a
  Git-pinned plugin, changing the pin requires an explicitly chosen full commit
  via Hermes install. Never self-update or replace this plugin from PyPI.
- If the installation is pinned to a Git URL, an upgrade may keep that old revision.
  Explain it and ask before migrating to PyPI or uninstalling anything.
- Run doctor again; preserve all user-owned state and stop for unresolved requirements.

After setup, use `skill_view("by2kb:video-to-knowledge")` for manual ingestion.
````

## File: README.md
upstream: https://github.com/charlesmpc/by2kb/blob/main/README.md

````text
# by2kb

**Forward a video. Keep the knowledge.**

`by2kb` turns a video URL into three durable Markdown artifacts in your own knowledge
base: the evidence-preserving transcript, a short “is this worth reading?” abstract,
and long-form study notes.

The primary user is an **agent user**. Send a Bilibili URL or media attachment to an
agent such as Hermes; `by2kb` handles media retrieval and the selected local or cloud
ASR provider, while the agent uses its existing model authentication to produce both summaries.
Standalone users can run the same pipeline with their own OpenAI-compatible API key.

**Learning-topic discovery (new in 0.7.0).** Send
`by2kb 我想了解一下 TiDB 向量检索` through the updated Hermes plugin to get
separate Bilibili and YouTube recommendation lists (up to 3–5 videos per enabled
source in 0.7.5), then reply with a globally unique number to enter the normal
transcription and knowledge-base workflow. Search sources are individually configurable;
caption-only previews never download audio or run ASR. See
[topic search and configuration](docs/topic-search.md) for CLI usage, selection
state, preview limits, and deployment requirements. Current built-in search sources
are Bilibili and YouTube; podcast and article ingestion remain future extensions.

## See it in action

**Save a video you like. Or explore a topic you want to learn.**

- **Save a video:** send its link to Hermes, then keep the transcript, short abstract,
  and study notes in your own knowledge base.
- **Explore a topic:** ask Hermes about a learning topic, browse relevant video
  recommendations, and reply with a number to transcribe and save your selection.

https://github.com/user-attachments/assets/0cbec29a-f2a7-4279-bff1-a3c021574808

*36.6-second demo (by2kb 0.7.3): two Hermes-on-Telegram workflows, with Chinese
captions. Processing waits have been cut for brevity, not shown in real time.
Sound optional.*

> **[Latest release](https://github.com/Charlesmpc/by2kb/releases/latest).** Agent-guided installation, a cloud-free local Whisper
> default, upgrade-safe personalization, Bilibili/YouTube ingestion, Agent/API
> enrichment, task control, and the Hermes plugin are implemented. A resident service,
> native Telegram/Lark bots, and remote knowledge-base sinks remain planned.

## Start here

Requires Python 3.12+, `pipx`, and `ffmpeg`/`ffprobe` on PATH. YouTube player
challenges also need Deno 2.3+ or Node.js 22+; matching EJS scripts ship with the
Python dependencies. `by2kb doctor` checks both. See [YouTube JS setup](docs/source-providers.md#youtube-javascript-support).

### Ask your Agent to install it

Send this prompt to an Agent with terminal access:

```text
Read and follow the official by2kb installation skill:
https://raw.githubusercontent.com/Charlesmpc/by2kb/main/skills/install-by2kb/SKILL.md
```

The installation Skill defaults to local faster-whisper, Agent-hosted summaries,
Bilibili and YouTube sources, and a local Markdown knowledge base. It does not clone
the repository or ask for cloud credentials in chat.

Upgrades replace application and adapter code but preserve `$BY2KB_HOME` (normally
`~/.by2kb`), the configured knowledge-base folder, downloaded models, job history,
credentials, and custom Skills. See [Upgrading](docs/upgrading.md).

### Install it yourself

Install the published package with local Whisper and YouTube support:

```bash
pipx install "by2kb[asr-whisper,youtube]"
by2kb init --preset agent-local
by2kb models install
```

Cloud Doubao ASR remains available for machines that should not run Whisper locally:

```bash
pipx install "by2kb[asr-doubao,youtube]"
by2kb init
```

`by2kb init` guides you through four decisions:

1. where the local knowledge base should live;
2. whether transcription uses local faster-whisper or cloud Doubao AUC;
3. local model settings, or the private TOS bucket and Doubao credentials;
4. whether summaries run in an agent (`agent`), through a standalone LLM API (`api`),
   or remain disabled.

After installing the selected optional ASR runtime/model, verify the deployment:

```bash
by2kb doctor
by2kb doctor --json
```

Bilibili and YouTube are enabled by default, and yt-dlp ships with the base package.
YouTube uses available captions first, then the configured ASR when audio is needed.
No separate platform configuration is required. Explicit source overrides remain
respected; see [upgrading source defaults](docs/upgrading.md#bilibili-and-youtube-defaults)
if an older configuration deliberately or historically lists only Bilibili.

### Agent-first: Hermes

After selecting `agent` during initialization:

```bash
by2kb agent install hermes
hermes gateway restart
```

These commands are for the legacy copy-based adapter installation. If Hermes
already manages your by2kb plugin through Git or the catalog, do not reinstall it
with the copy installer. See [native plugin setup](docs/agent-integration.md#native-hermes-installation-and-first-setup)
and [upgrade ownership](docs/upgrading.md#managed-code). Catalog submission is pending.

Now an authorized user can send a Bilibili, `b23.tv`, YouTube, or `youtu.be` URL to
the Telegram Hermes bot.
The plugin acknowledges immediately, runs transcription in the background, calls the
Hermes host model through bounded staged operations, writes all three artifacts, and
replies with the short abstract and knowledge-base paths. No MCP server and no
separate by2kb LLM key are required.

### Standalone

Select `api` during initialization, provide an OpenAI-compatible endpoint, model and
API key, then run:

```bash
by2kb ingest "https://www.bilibili.com/video/<bvid>/"
by2kb ingest ./meeting.mp3
by2kb ingest ./lecture.mp4
```

See [Agent integration](docs/agent-integration.md) for the reusable staged
`ingest → next → submit` enrichment contract used by other agent hosts.
See [Agent task control](docs/task-control.md) for the versioned
`status`/`wait`/`cancel`/`retry` protocol and checkpoint-aware retries.
See [ASR providers](docs/asr-providers.md) for optional local faster-whisper setup,
explicit model installation, and the existing cloud Doubao path.
**Bilibili HTTP 412?** Version 0.5.0 can recover from a blocked `view` request using
`pagelist` to obtain CID and continue native audio acquisition—no browser required.
An opt-in browser Plan B uses a dedicated Chromium session when native acquisition
fails. It requires the `browser` extra and manual login when the site requests it;
neither route guarantees recovery from all site risk controls. See the
[browser setup and fallback guide](docs/source-providers.md#browser-fallback-043-opt-in).

See [Source providers](docs/source-providers.md) for configurable provider priority,
default yt-dlp routing, caption policy, audio fallback, and cookie handling.
See [Local media](docs/local-media.md) for supported formats, content-addressed
deduplication, ffmpeg requirements, and attachment handling.
See [Diagnostics](docs/doctor.md) for every read-only check and the Agent-facing JSON schema.
See [Transcript quality](docs/transcript-quality.md) for deterministic enrichment gates,
recorded metrics, and warning behavior.
See [Long-form enrichment](docs/long-form-enrichment.md) for segment-safe planning,
intermediate caching, recursive reduction, and provenance.
See [Agent enrichment provider](docs/agent-enrichment-provider.md) for the bounded
callback protocol and API-key versus subscription/OAuth authentication tradeoffs.

The name can be read as **B/Y to KB** — Bilibili and YouTube to Knowledge Base — while
the architecture is intended to support more video sources over time.

## Why

Most video tools optimize for watching, summarizing, or taking notes inside a browser.
That is useful, but it is not the workflow this project wants:

- Interesting videos are often discovered in a mobile app.
- A browser extension should not be required to keep a desktop computer online.
- The transcript should become a portable artifact, not remain in extension storage.
- The ori
````
