dsh-acfun/README.md

dsh-plugin-acfun

DeepSeek Harness plugin for AcFun (A站, acfun.cn): search videos, read video metadata, comment threads, danmaku (弹幕), the day/week ranking, playable stream URLs and 动态 (moments); interact with your own account (like, tip bananas, favorite, follow, comment — including moments); and sign in by scanning a QR code in the Harness Web UI (Settings → AcFun).

This is the AcFun counterpart of the community Bilibili tool plugins. Reads are anonymous and work out of the box; every mutating call is gated behind allowWriteActions: true and an AcFun login cookie, so installing the bundle never silently gives the model write access to an account.

Tools

Tool	Kind	What it does
acfun_search	read	Keyword video search; sort: "views" orders by play count (AcFun returns one fixed first page of up to 30).
acfun_video	read	Full metadata for one video: author, channel, tags, stats, publish time, cover.
acfun_comments	read	One page of a video's comment thread, in floor order.
acfun_danmaku	read	One batch of a video's 弹幕, ordered by in-video position, with cursor paging.
acfun_rank	read	Day or week ranking, all channels or one channelId.
acfun_playurl	read	m3u8 quality ladder (1080P+ / 1080P / 720P / 540P / 360P).
acfun_moment	read	One 动态 by id: text, topics, images, author, counts, canonical share URL.
acfun_moment_comments	read	One page of a 动态's comment thread (moments have their own comment enum).
acfun_topic	read	社区圈 topic page (best effort, 15 newest items) — the only public way to discover current moment ids.
acfun_interact	write	Video: like, unlike, banana, favorite, unfavorite, follow, unfollow. Moment: moment_like, moment_unlike, moment_banana.
acfun_post_comment	write	Post a top-level comment or reply on a video (acId) or a 动态 (momentId).
acfun_account	read	Login state, credential source, whether interactions are enabled, and the next sign-in step.

A model-facing skill (skills/plugin-tool-acfun/SKILL.md) teaches the tool sequence, the write-safety rules, and the 动态 limitations.

Install

Install the workspace directory as a profile bundle:

plugin_manager action=install_bundle target=C:\path\to\dsh-acfun

The bundle inserts two Loader rows: acfun (the tools, panel API and QR login) and acfun-skill-filesystem (which exposes this package's skills/ directory to the agent). A local directory is linked, so edits to the plugin need a Harness restart to load a fresh module generation.

To remove it, use plugin_manager action=remove_bundle target=dsh-plugin-acfun.

QR login and the Web UI panel

The bundle ships a Client half (client.js) that adds a Settings → AcFun page. It shows the current login state, the credential source and whether interaction tools are enabled, renders the QR code, and polls until the phone confirms.

Flow (all Host-side, lib/qr-flow.js):

1. GET https://scan.acfun.cn/rest/pc-direct/qr/start?type=WEB_LOGIN returns a base64 PNG plus qrLoginToken, qrLoginSignature and expireTime (120 s).
2. scanResult is a single long-poll held by AcFun until the phone scans or the code expires. On scan it returns a rotated signature.
3. acceptResult with the rotated signature issues the session cookies; the plugin captures Set-Cookie, persists the cookie through the Host credential service (acfun-session grant record), and points the provider at it.

The panel talks to the Host over /acfun-panel/* (same-origin JSON, cross-origin requests rejected). Scanning a QR code is the only step a plugin cannot verify by itself, so the confirm branch is exercised only by a real phone scan.

Restart requirement: a Client half added to a package that the Host already scanned needs one Harness restart, then a page reload, before Settings → AcFun appears. The graph is composed from the live Loader entry set at boot, so a bundle installed into a running page is not in it yet. Detect it with GET /acfun-panel/state (client.path must be non-null) or GET /acfun-panel/diagnose; details and evidence are in docs/client-panel.md.

Configuration

The row config lives in cordis.patch.yml; every key is optional.

Key	Default	Meaning
cookie	''	Full AcFun Cookie header value. Prefer the environment variable so the secret does not enter the patch.
cookieEnv	ACFUN_COOKIE	Environment variable read when cookie is empty.
allowWriteActions	false	Master switch for acfun_interact and acfun_post_comment.
requestTimeoutMs	30000	Per-HTTP-request timeout.
timeoutMs	45000	Cooperative per-tool-call budget (write calls use at least 60 s).

A cookie from the panel's QR login is stored as a credential record and wins over cookie/ACFUN_COOKIE; signing out in the panel falls back to the config.

Example with the environment variable:

$env:ACFUN_COOKIE = 'auth_key=...; acPasstoken=...; _did=...'

Getting the cookie without the panel

1. Sign in to https://www.acfun.cn/ in a desktop browser.
2. Open DevTools → Network, reload any acfun.cn page, and copy the complete Cookie request header of the document request (it contains auth_key, acPasstoken, _did, and other session values).
3. Paste it as one line into cookie or ACFUN_COOKIE.

Treat that string like a password: it grants full access to the account. The plugin never logs it.

Safety model

• Reads cannot mutate anything and need no cookie.
• Writes require both allowWriteActions: true and a cookie. With only one of them the tools return WRITE_DISABLED / LOGIN_REQUIRED and perform no HTTP write request.
• Write tools are declared non-concurrency-safe so the harness will not run two account mutations in parallel.
• A CAPTCHA/identity-verification challenge from AcFun (result 400001–410999) is surfaced as CAPTCHA_REQUIRED; the plugin never tries to solve it.

Verification status

Verified live on 2026-10-27 against acfun.cn (anonymous):

• All six read tools — acfun_search (including sort: "views"), acfun_video, acfun_comments, acfun_danmaku, acfun_rank, acfun_playurl, acfun_moment, acfun_moment_comments, acfun_topic — return real API data and pass output-schema validation plus rendering (node scripts/live-check.mjs).
• QR login issuance and the waiting/abort path were verified live against scan.acfun.cn (a real ticket and PNG are returned; an unscanned ticket holds the long-poll until the 120 s expiry, then reports "expired").
• All twelve tools register through a mock Cordis context, the panel routes are served on a local HTTP server, and the write guard fails closed (node scripts/self-check.mjs).
• Write routes exist and reject anonymous requests with {"result":-401}. The authenticated happy path — including the final QR accept step and moment writes — was not exercised here because no AcFun account was available. Treat first use as a live test: check the result in the AcFun UI instead of retrying blindly.

Known limitations

• AcFun's pc-direct search endpoint ignores page/pageSize and always returns its first page (30 entries), so acfun_search cannot paginate. sort is the only ordering control AcFun honours.
• Bangumi (番剧) and article pages are not supported — acfun_video reports UNSUPPORTED_RESOURCE instead of guessing.
• No 广场 feed API exists. After ~560 path probes no public square/recommend moment list was found on any host; moment ids can only be discovered through acfun_topic (server-rendered, 15 newest items, no pagination) or a share link. The only moment lists are login-scoped following feeds.
• Publishing, deleting, reposting and voting on a 动态 are app-only behind the signed midground token; the web plugin cannot do them.
• Moment like/banana/comment contracts are derived from the site's own store and verified only up to their auth error (401), so treat moment writes as experimental.
• Danmaku paging beyond the first batch depends on AcFun's opaque pcursor; acfun_danmaku passes it through as cursor/nextCursor.
• Play URLs are time-limited signed m3u8 links; re-run acfun_playurl when one expires. Downloading/merging streams is out of scope.
• This plugin only talks to acfun.cn's public web endpoints; it is unofficial and can break when AcFun changes them.

Development

node scripts/self-check.mjs   # offline: exports, tool schemas, QR state machine, panel HTTP
node scripts/live-check.mjs   # online: real reads, QR issuance, schema validation + render

No build step, no runtime dependencies. Everything under lib/ and client.js is plain ESM/JavaScript that imports only Node built-ins/globals. The bundle intentionally exports no Config schema: a workspace-linked bundle cannot resolve @deepseek-ai/* packages, so lib/config.js validates the row config and falls back to defaults with warnings instead of using schemastery.

Endpoint notes: docs/acfun-api.md (videos/comments/danmaku/rank), docs/acfun-login.md (QR login), docs/acfun-moment.md (广场/动态 research and verdict).

License

MIT — see LICENSE.