Table of Contents
- FAQ
- Why 30 tools and not 5?
- Why LongPoll over Callback API?
- Why a separate moderation engine instead of letting the agent decide?
- Why no captcha solver?
- Why is vk_api_raw off by default?
- Why does vk_community_update default to dry-run?
- Why two tokens (community + user)?
- Why not use execute for everything?
- Why does the agent still see auto-moderated events?
- Why are join/leave notifications off by default?
- Why no standalone dashboard?
- Why not scrape other communities for competitive analysis?
- Why is the audit log never cleared by a tool?
- Why keyword moderation, not an LLM classifier?
- Why not auto-approve join requests?
- Why are join requests handled separately from member manage?
FAQ
Answers to questions where the design decision looks arbitrary.
Why 30 tools and not 5?
A "post to VK" tool with a huge args object is a failure mode: the model guesses field names, the schema does not enforce semantics, and the agent cannot call vk_wall_post programmatically in PTC mode because the schema is opaque. Narrow tools with typed schemas are the DSH idiom, give the model clear affordances, and let PTC code call them with compile-time types. Each tool is one VK intent; the schema is the contract.
Why LongPoll over Callback API?
Callback needs a public HTTPS endpoint. A local DSH install (the common case) does not have one. LongPoll is outbound-only, resume-capable through persisted ts, and has effectively the same latency because VK implements it as a long-poll. Callback exists for deployments that already have a public host and want push.
Why a separate moderation engine instead of letting the agent decide?
The engine is for the work that must be instant, consistent and free: a spam-bot posts a link, the post is gone before the agent has read it. The agent handles the rest. Mixing the two — routing every comment through the model — costs money, adds latency, and makes the community's behaviour depend on the model's mood. The engine is the knowledge a human moderator would encode as rules; the agent is the judgement on top.
Why no captcha solver?
Automated captcha solving violates VK ToS and is a direct path to a permanently banned token. The plugin surfaces the captcha sid and either fails or asks a human — that is the correct behaviour, not a missing feature.
Why is vk_api_raw off by default?
It is an escape hatch, not a default. A raw-API call bypasses the schema validation that gives you the schema-as-contract property, so the model could do things the typed tools were designed to prevent. It exists, the wiki says when to use it, and the config flag makes it an explicit decision.
Why does vk_community_update default to dry-run?
Changing community settings is the one action that is both high-impact and trivially mistyped (e.g., closing the wall, flipping age limits). Requiring an explicit dryRun: false is cheap insurance. The pre-execute gate makes it ask on top.
Why two tokens (community + user)?
Because the community token cannot read its own member list or stats. The user token can. Supporting only one token means either losing members/stats (community-only) or impersonating the admin on every post (user-only). Both are worse than supporting both with clear per-tool scoping.
Why not use execute for everything?
execute batches ≤25 calls into one HTTP request and is the right choice for batch operations (bans, member manage). Using it for every method hides per-call errors, complicates replay, and makes the audit log coarser. The default is a direct call; batch is only for the batch tools.
Why does the agent still see auto-moderated events?
Because hiding them would make the community's own automated behaviour invisible to the operator. The agent is told "this was already actioned by rule X" so it does not repeat the action and can, if asked, explain what happened.
Why are join/leave notifications off by default?
A busy community generates a lot of join/leave noise. The default is to surface only message and comment events — the things that need the agent's attention. Join/leave is opt-in for communities that use a welcome flow.
Why no standalone dashboard?
State belongs in ctx.storage; presentation belongs in the DSH Web client. Shipping a separate web app means a separate auth system, a separate database, and a second thing that can break. The plugin contributes panels and cards to the surface the operator is already in.
Why not scrape other communities for competitive analysis?
It is a ToS violation, it is fragile, and the plugin's job is to manage one community well, not to duplicate a web scraper.
Why is the audit log never cleared by a tool?
Because the log is the record of who banned whom and when — it must survive the agent that made the decision. Rotation keeps the size bounded (last 10 000 records); deletion-by-tool is not a feature. If the log must be cleared, that happens out-of-band through ctx.storage by a human.
Why keyword moderation, not an LLM classifier?
Predictability, auditability, zero cost, zero latency. An LLM classifier running on every comment would rate-limit a busy community inside a minute. The agent can still be asked to review flagged items — that is a tool call, not an automatic action that runs on every event.
Why not auto-approve join requests?
Every community that auto-approves becomes a target for spam-bot registration. The autoApprove: true flag exists; the wiki discourages it; the audit log records it. The default is false.
Why are join requests handled separately from member manage?
Because in a closed community the join request is the only entry a moderator normally needs to see — a decision point — while vk_members_manage is for existing members. Splitting them matches how VK structures the API and how a human moderator thinks about it.