OKKO

OKKO is a managed KOOK HTTP/Gateway protocol client with persistent CloakChromium Profiles, headed login takeover, verified headless sessions, full-field local storage, media archival, and confirmed write plans.

Install

npm install --global @follenfang/okko
okko setup
okko doctor

npx --yes @follenfang/okko is also supported. The npm launcher installs a managed Python 3.12 runtime, locked Python dependencies, CloakChromium, and the packaged Codex Skill. Downloads use eight concurrent resumable Range workers, hash verification, and atomic activation.

Set OKKO_DOWNLOAD_CONCURRENCY to an integer from 1 through 64 to tune the Python runtime archive download. CloakChromium is installed by the version-pinned cloakbrowser pip package into the managed browser cache. okko doctor reports both download strategies. On Windows, console JSON is ASCII-safe so Windows PowerShell 5.1 can pipe it through ConvertFrom-Json without code-page damage; files and Python subprocess streams remain UTF-8.

Profile And Login

okko profile create --profile work --display-name Work
okko profile login --profile work --url https://www.kookapp.cn/app/discover
okko profile status --profile work

Login opens a headed browser for takeover, preserves the same Profile, then switches to headless and verifies authentication against the live user-state API. Credentials remain in browser/session memory and are redacted from output.

Protocol Reads

okko guilds list --profile work
okko channels tree --profile work --guild-id GUILD_ID
okko members collect --profile work --guild-id GUILD_ID
okko members online --profile work --guild-id GUILD_ID
okko messages collect --profile work --channel-id CHANNEL_ID
okko private conversations --profile work
okko private conversation --profile work --conversation CONVERSATION_ID
okko threads list --profile work --channel-id CHANNEL_ID
okko threads post-count --profile work --channel-id CHANNEL_ID --thread-id THREAD_ID
okko threads collections --profile work
okko threads collected --profile work --guild-id GUILD_ID --channel-id CHANNEL_ID
okko guilds emoji --profile work --guild-id GUILD_ID
okko protocol schema

Remote responses are stored as append-only raw envelopes and normalized observations. Unknown fields are preserved. sync, query, media fetch, and protocol gateway cover incremental collection, local reads, SHA-256 media archival, and live events.

sync accepts repeated resources and selectors. --resource all collects all enumerable guild, channel detail, member, online, message, conversation, thread, collection, post, media, and Gateway families. Repeated --guild-id, --channel-id, --conversation-id, and --thread-id limit the scope. --since and --until are inclusive Unix epoch boundaries; seconds are normalized to milliseconds. Each window has an independent checkpoint and failures produce a partial summary without discarding successful resources.

Confirmed Writes

Writes are two phase. The first command creates a time-limited plan; execution requires explicit confirmation and is claimed atomically once.

okko channel send --profile work --channel-id CHANNEL_ID --text "hello"
okko channels create-post --profile work --guild-id GUILD_ID --name "forum"
okko threads category-create --profile work --channel-id CHANNEL_ID --name "general"
okko threads create --profile work --guild-id GUILD_ID --channel-id CHANNEL_ID --category-id CATEGORY_ID --title "title" --content "body" --cover-file COVER --image-file IMAGE --file FILE --tag-id TAG_ID
okko plan confirm --profile work --plan-id PLAN_ID
okko channel execute --profile work --plan-id PLAN_ID
okko protocol reconcile --profile work --plan-id PLAN_ID

Channel writes support text/card combinations, member/role/everyone/online mentions, replies, uploads, update, pin, unpin, and delete. Private messages support text, image/file uploads, replies, update, and delete. Threads support categories, cover, tags, rich content, replies, move, pin, update, collect/uncollect, post reactions, and delete. Thread category names contain at most 10 characters. Post create/update can upload a local cover, body image, and body file in one confirmed operation. Thread updates preserve omitted category, cover, tag, and cover-visibility fields from the current remote record; use --no-show-cover for an explicit false value. Collection policy errors are returned without replaying writes. Use each subcommand's --help for its typed arguments.

Broker

okko broker serve --profile work
okko broker status --profile work
okko broker state --profile work
okko broker gateway-start --profile work
okko broker gateway-status --profile work
okko broker gateway-stop --profile work
okko broker stop --profile work

The persistent control plane is loopback-only NDJSON with a private token, serialized commands, production HTTP/multipart transport, background Gateway, and uninstall registration. Protocol commands automatically reuse the one active Broker for the same Profile and project root; zero registrations use a short session and conflicting registrations fail explicitly. Read-side 401 responses refresh the in-memory session once, while mutations are never automatically replayed. Project data stays under profile/ and message/; managed runtime data stays under OKKO_HOME.

Publishing

The release workflow uses npm Trusted Publishing with these fields:

Provider: GitHub Actions
Organization/User: Follen
Repository: okko
Workflow filename: publish-npm.yml
Environment: npm

Tags matching v* run the complete CI matrix before OIDC publication.