Documentation Sync
This page translates plugins/adapters/bilibili/README.md. Keep this English page aligned with the README; pnpm sync:adapter-docs updates the Chinese pages.
@zhin.js/adapter-bilibili
Experimental — built on Bilibili's unofficial Web APIs (including the QR login API) and may break at any time when the site changes. Not part of the stable smoke suite; config and behavior may change incompatibly.
Zhin.js Bilibili comment adapter (Plugin Runtime): lets AI help you reply to comments under your own videos, dynamics and articles. Contract: ADR 0035: Comment-reply adapter contract. Discussion: #971.
Read this first
- It acts as your account: Bilibili's open platform grants no comment read/write scopes, so this adapter uses your login cookies (
SESSDATA+bili_jct). The recommended way is QR login on the Console "Comment review" page; the credentials stay only in the data directory of the machine running the bot (data/bilibili/<account>/credentials.json, mode 600). Environment variables still work. Treat cookies like a password: never put them inzhin.config.ymlin plain text, commit them, or paste them into logs or issues. - Review before send by default:
sendModedefaults toreview. AI-written replies only land in a draft queue and are never posted to Bilibili automatically; they are posted only when you press Send on the Console "Comment review" page or a master runsbili-draft send <id>. There is no auto-send. - Allow-listed content only: only the videos, dynamics and articles listed in
videos/dynamics/articlesare polled (ideally your own); a blank list polls nothing of that kind. No site-wide search, no posting in other people's comment sections. Follow Bilibili's user agreement — no marketing, lead generation, or spam. - Risk control trips a breaker: on rate-limit / captcha / risk-block / duplicate-comment codes the endpoint stops polling and logs an error with no automatic retry; restart after checking the account manually.
Current capabilities
| Capability | Status |
|---|---|
| BV id → aid | ✅ |
Poll latest comments on allow-listed videos (x/v2/reply, video type=1) | ✅ read-only |
| Detect own uid from the login, skip own comments | ✅ |
One comment thread = one conversation (<resource>:<oid>:<rootRpid>, e.g. video:<aid>:<rpid>) | ✅ |
| First poll only records a baseline (history is not fed to AI) | ✅ |
AI replies go to a draft queue (review) | ✅ |
| Draft persistence (survives restarts; interrupted sends are flagged) | ✅ data/bilibili/<account>/drafts.json |
Posting after master approval (bili-draft send → x/v2/reply/add) | ✅ with send interval and risk breaker |
Edit / discard drafts before sending (bili-draft edit / drop) | ✅ |
QR login / cookie persistence (Console page or bili-login start) | ✅ environment variables still work and take precedence |
| Expired-cookie detection: clear stale credentials, ask you to scan again | ✅ |
| Console "Comment review" page: login status, watched videos / dynamics / articles, send / edit / discard drafts | ✅ |
Push new drafts / expired login to you (notify) | ✅ optional, via the unified outbound pipeline to a chat you choose |
"Replies to me / @me" notifications (x/msgfeed/reply, x/msgfeed/at) | ✅ needs a login, off by default; video comments, plus dynamic / article comments when dynamics / articles are configured |
Dynamic comments (dynamics: dynamic id → comment area via dynamic detail; image posts type=11, text / forward posts type=17) | ✅ Experimental |
Article comments (articles: cv ids, type=12) | ✅ Experimental |
Prerequisites
- Your own Bilibili account and the BV ids / dynamic ids / article cv ids to manage (ideally your own)
- Pick one way to sign in:
- QR login (recommended): after starting, open the Console "Comment review" page, press "Sign in with QR code", and confirm in the Bilibili app; or send
bili-login startto the bot in a private chat (the QR code is only sent in private chats) - Environment variables: log in at bilibili.com, copy
SESSDATAandbili_jctfrom DevTools → Application → Cookies, and put them in a gitignored.env:BILIBILI_SESSDATA,BILIBILI_BILI_JCT
- QR login (recommended): after starting, open the Console "Comment review" page, press "Sign in with QR code", and confirm in the Bilibili app; or send
- Keep the
data/directory out of the repository (projects fromcreate-zhin-appalready ignore it; check.gitignorein your own projects) - Cookies expire; the page then shows "Login expired" and the log shows
bilibili_login_invalid— scan again
Required fields (endpoints[i]): id. Read-only public comment polling works without signing in.
Minimal Configuration
configVersion: 2
plugins:
bilibili: "@zhin.js/adapter-bilibili"
bilibili:
sendMode: review # default; off = no outbound at all
pollIntervalSec: 60 # minimum 60
minSendIntervalSec: 30 # minimum gap between two approved posts, at least 10
notifications: [reply, at] # optional: also receive "replies to me / @me"; off by default
notify: # optional: tell you about new drafts / expired login
adapter: icqq # the adapter you chat with the bot through
endpoint: my-qq # that adapter's endpoints[i].id
id: "10001" # your account (private chat)
endpoints:
- id: my-bilibili
videos:
- BV1xx411c7mD # your own videos only
dynamics: # optional: dynamic ids (the number in t.bilibili.com/<id> or bilibili.com/opus/<id>)
- "1073543151725051921" # always quote: dynamic ids exceed JS safe integers and unquoted values are rejected
articles: # optional: article cv ids
- cv40000001
# Only when using environment variables instead of QR login:
# sessdata: ${BILIBILI_SESSDATA}
# biliJct: ${BILIBILI_BILI_JCT}After starting, open "Comment review" in the Console and scan the QR code. Without signing in the adapter can still poll public comments, but it cannot identify your account (so it cannot filter self-replies), send, or receive "replies to me / @me".
Login and credentials
- Precedence: a valid cookie from config / environment variables wins over stored QR credentials; when none is configured or it has expired, the stored QR login is used.
- Location:
<endpoint id>/credentials.jsonunderdataDir(defaultdata/bilibili, relative to the working directory), file mode 600. Never in YAML or logs. - Expiry: when the startup check or a send reports "not logged in", stale QR credentials are deleted, the page shows "Login expired", and
notifyasks you to scan again. Drafts are kept. - Sign out: "Sign out" on the Console page deletes the stored QR credentials; cookies from environment variables can only be changed there.
- QR safety: the QR image is rendered locally, never sent to a third-party QR service or written to logs;
bili-login startonly answers in private chats.
Console "Comment review" page
With the Console installed, "Comment review" appears in the navigation (route is the plugin path, such as /bilibili). There you can:
- See the login status; sign in with a QR code, scan again, or sign out
- Review pending replies: the original comment and the AI's proposed reply, with Send / Edit / Discard
- See the watched videos / dynamics / articles (read-only; edit the config to change them); dynamics that cannot be resolved are marked as skipped
The page refreshes every 10 seconds (2 seconds while scanning), so new drafts appear automatically.
Permissions (plugin-defined, granted by level — see Plugin permission levels: bilibili:read is read level, held by viewer and above; bilibili:review and bilibili:login are operate level, held by operator and above; a global owner is unrestricted):
| Permission | Allows |
|---|---|
bilibili:read | Open the page, read status and drafts |
bilibili:review | Send / edit / discard drafts |
bilibili:login | QR login / sign out |
Review commands require the chat role owner: grant yourself owner on the chat adapter you talk to the bot through (QQ / Telegram, …) in the Roles tab of the Console object pages or with role grant (see Chat roles); to run them from Bilibili comments your Bilibili identity needs owner too. With no owner, nobody can send via commands.
Conversations and messages
conversation.kind = 'channel',id = <resource>:<oid>:<rootRpid>,parent = <resource>:<oid>message.id= commentrpidsender= commenter uid / nicknamemetadata:resource(type/oid/commentType/dynamicId?/url),rootId,parentId,via(video/album/dynamic/article/reply/at),createdAt,likeCount,isUploader
Each resource prefix maps to exactly one Bilibili comment area, so the conversation id alone decides where a reply is posted:
| Prefix | Comment type | oid | Source |
|---|---|---|---|
video | 1 | video aid | videos |
album | 11 | album id (not the dynamic id) | image posts in dynamics |
dynamic | 17 | the dynamic id itself | text / forward posts in dynamics |
article | 12 | article cvid | articles |
Each entry in dynamics is resolved once at start through dynamic detail (x/polymer/web-dynamic/v1/detail), using the platform-declared basic.comment_type / basic.comment_id_str instead of guessing an oid. Video dynamics (type=1) belong in videos and article dynamics (type=12) in articles; those, deleted / hidden dynamics and other unsupported shapes are skipped (logs bilibili_dynamic_unsupported / bilibili_dynamic_unresolved) without affecting other resources.
- Comments from "replies to me / @me" carry
mentioned: true; nested replies carryreplyTo
Group-style trigger rules apply: a comment thread is a shared conversation, so AI is triggered by @ / prefix by default; "replies to me / @me" count as @-ing the bot.
Replies to me / @me
With notifications: [reply, at], each poll also reads one page of x/msgfeed/reply / x/msgfeed/at:
- The first poll only records a baseline; afterwards only new notifications are admitted
- Video comments (
business_id=1); dynamic comments (11 / 17) whendynamicsis configured, article comments (12) whenarticlesis configured; other businesses are ignored notificationScope: whitelist(default) admits only notifications under allow-listed videos / dynamics / articles;alladmits every video-comment notification plus every dynamic / article comment notification of the enabled kinds (for example replies to your comment under someone else's video)- Text-dynamic oids (dynamic ids) exceed JS safe integers, so the notification number loses precision: the adapter recovers the exact id from the notification link and requires it to match; otherwise the notification is dropped rather than replied to in the wrong thread
- A comment seen by both the video poll and a notification is admitted once
Outbound
send({ conversation, payload }) accepts comment-thread conversations only and keeps plain text (≤1000 chars). It always only puts the reply into endpoint.drafts and reports "not sent, awaiting approval" via EndpointDeliveryError('approval_pending', …, 'not_sent'). A reply segment (comment rpid) in the payload targets that nested comment; otherwise the reply goes to the thread root.
Reviewing drafts
The Console "Comment review" page is the easiest way; commands also work (owner-only, from any connected chat platform):
| Command | What it does |
|---|---|
bili-draft list | List pending drafts (id, quoted original comment, proposed reply) |
bili-draft show <id> | Show one draft in full |
bili-draft edit <id> <new text> | Rewrite a draft; it still needs send |
bili-draft send <id> | Approve and post (x/v2/reply/add); returns the comment link |
bili-draft drop <id> | Discard without sending |
bili-login start [account] | QR login (the QR code is only sent in private chats) |
bili-login status | Show the login status and pending count |
Drafts are stored in data/bilibili/<account>/drafts.json and restored on restart (the latest 200 are kept). A draft whose send was interrupted by a process exit is flagged "last send was interrupted and may have been posted"; check Bilibili before sending it again.
Send guards: sendMode: off, an open breaker, no valid login, or less than minSendIntervalSec since the last post are refused outright (the draft is kept; no queueing, no automatic retry). A risk-control code while posting trips the breaker for the whole endpoint.
Code can call endpoint.approveDraft(id) / editDraft(id, text) / discardDraft(id) and startQrLogin() / logout() directly.
Notifications to you
With notify configured, these events send one message to that conversation through the unified outbound pipeline (OutboundHost):
- A new draft: original comment excerpt, proposed reply, how to approve
- Expired login: scan again (or update the environment variables)
- QR login succeeded
Without notify, drafts only show on the Console page and in logs (bilibili_draft_queued). A failed notification is only logged and never affects the draft.
Known Limitations
- Unofficial APIs; signature, field, or QR-flow changes on Bilibili's side can break it outright
- Only the first page of each comment area (latest 20 by time) is polled; more than 20 new comments between polls will be missed
- Seen comment ids and notification baselines live in memory; a restart re-baselines (old comments from the downtime are not handed to AI)
- No automatic cookie refresh; scan again after expiry
- "Replies to me / @me" reads only the first notification page per poll
- Only video (
type=1), image-post (type=11), article (type=12) and text / forward dynamic (type=17) comments; dynamic → comment-area mapping depends on the dynamic detail API and may stop resolving after platform changes (such dynamics are skipped, never guessed) - Dynamics are resolved when the endpoint starts (like BV ids in
videos) and are not re-resolved while running
Troubleshooting
| Symptom | Action |
|---|---|
Log bilibili_circuit_open | Risk control triggered (rate limit / captcha / block / duplicate). Polling stopped: check the account on the website, complete verification if needed, raise pollIntervalSec, then restart |
Log bilibili_login_invalid / page shows "Login expired" | The cookie expired. Scan again for QR logins; update the environment variables (or remove them and scan) otherwise |
| QR login says Bilibili risk control blocked it | The QR API is rate-limited; wait a few minutes and retry |
Log bilibili_no_videos | videos / dynamics / articles are empty (or no dynamic could be resolved); nothing will be polled |
Log bilibili_dynamic_unsupported | The dynamic's comment area is unsupported (put video dynamics in videos, article dynamics in articles); skipped |
Log bilibili_dynamic_unresolved | Dynamic detail returned an error (deleted / hidden); skipped |
Startup error lost precision | A dynamic id in dynamics is unquoted; make it a string |
| AI replies don't show up on Bilibili | Expected: only drafts are created (bilibili_draft_queued); press Send on the Console page or run bili-draft send <id> |
| No "Comment review" in the Console | Make sure the Console (@zhin.js/page) is installed and the token has bilibili:read |
| Page buttons say you lack permission | The token lacks bilibili:review / bilibili:login |
bili-draft send says it is too soon | minSendIntervalSec has not passed; try again later, the draft is kept |
bili-draft reports no permission | You do not hold the chat role owner; grant it in the Roles tab of the Console object pages |
Log bilibili_notifications_disabled | notifications is on but you are not signed in, so notifications are not polled |
Log bilibili_notify_failed | The notify conversation cannot be reached: check adapter / endpoint / id and that the adapter is online |
Log bilibili_draft_persist_failed | The data directory is not writable; check dataDir permissions. Drafts remain in memory |
References
The QR login and overall flow borrow ideas (flow only — no copied code, no dependency) from renmu123/biliAPI (WebQrcodeLogin), WittF/bilibili-qr-login, Ninzore/bilibili-captain (Login.loginQR) and Janson20/BiliCommentBot. The community API docs SocialSisterYi/bilibili-API-collect are archived; this adapter does not depend on them. Endpoints may change at any time — see the Experimental note at the top.