Lv QuickGate (小驴快门)

The Lv ecosystem hub & external gateway for SiYuan — one public contract (39 ops) for Quicker / Shortcuts / CLI / AI assistants

中文文档 · Getting started · op contract · AI client matrix · Download

Outside clients (Quicker, iOS Shortcuts, CLI, PowerShell, AI assistants, HA scripts…) and sibling plugins share one public contract (39 ops):

• commands.* — discover / search / run command-palette entries of any installed plugin (confirm-gated, audited; search understands zh/en/pinyin aliases — 打卡/daka/checkin all hit)

• checkin.* / contacts.* — structured pass-through to the public bridges of Lv Check-in (API v5) and Lv Contacts (bridge v1)

• favorites.* — favorites & recent usage (command-palette UX: dedupe-and-move-to-front, privacy clearing; stored separately from bridge files)

• registry.list / diagnostics.report / config.discover — Lv ecosystem manifest (8 plugins, public installation/enabled metadata and read evidence), sanitized diagnostics, daily-note notebook + inbox auto-discovery

• Command forms provide read-only invocation checks and recheck before dispatch; unknown business configuration remains explicit. Contacts currently support protocol v1; v2 returns unsupported pending adaptation.

• events.list / events.pull — whitelisted event stream (check-in record/deletion auto-materialized; deletions as :deleted-suffixed markers coexisting with originals)

• workflow.plan / workflow.execute — controlled orchestration (≤8 steps, op whitelist, 30s total confirm, stop-on-failure)

• template.new / doc.open / daily.status / editor.context / setting.open — doc-from-template, controlled navigation, editor context

• plugin.api — raw bridge pass-through (off by default + allowlist + manifest-driven window-bridge mapping)

Three channels (all speaking the same envelope, sharing one idempotency ledger):

Marketplace status: deferred. GitHub Releases is the single distribution channel for now (see install below).

In-plugin UI (SiYuan side)

Visual language follows design/ui-prototype/mvp1.html (all --b3-* tokens, follows the host theme's light/dark mode, no hard-coded colors):

• Layered settings panel: Status overview (health home: channel cards / run KPIs / next step / recent receipts) · First-run wizard (resumable seven-step state machine: env check → capability selection → bridge permission → connection probe → sample read → optional sample write (undoable) → done; wizard-state.json resume) · Connections · Security · Queue & data (incl. full backup/restore and clear-queue preview) · Diagnostics & ecosystem · About; a top search bar filters settings across groups.

• Command palette (Ctrl+Alt+P): search host commands (zh/en/pinyin aliases, favorites ★ / recents auto-pinned); "capability actions" run in two stages (fill params, then execute, write-ops annotated); empty-result fallback = one-line quick capture to today's daily note / inbox.

• Notification / Recovery / Results centers: aggregated attention items (one-click jump to the handling surface) · manual disposition of unknown/failed/expired receipts (retry with a new id / dismiss with record / batch) · results.ndjson query (status/time filters, keyword, paging, CSV/JSON export).

• Liveness detection & takeover: when another window holds the consumer lock, its heartbeat status is shown; stale/suspect heartbeats offer one-click takeover (ledger prevents double consumption).

Related MCP server: siyuan-ai-mcp-bridge

Install (manual)

1. Download package.zip from Releases. A prerelease is for public testing; GitHub shows the uploaded asset's SHA-256 digest. Releases from v0.9.0 on are stable (non-prerelease) — just pick the latest one.

2. SiYuan → Settings → Marketplace → Downloads → top-right menu → Install from package → pick the zip.

3. Enable the plugin, open its settings, switch External command bridge on (default off by design).

4. After updating, fully quit SiYuan (tray → quit) and start it again — reopening the window does not refresh plugin frontend code. Or just double-click tools/restart-siyuan.bat.

Before enabling external access, configure SiYuan's access authorization code and use its API token in clients. A kernel with an empty access authorization code permits local anonymous access; QuickGate's private HTTP route inherits the host's authentication. Confirm unauthenticated requests are rejected with HTTP 401/403. Authenticated frontend sessions use the host's normal session mechanism.

Protocol

One NDJSON file set per plugin under data/storage/petal/<plugin>/bridge/:

commands.ndjson   # client → plugin, one JSON envelope per line
results.ndjson    # plugin → client, rolling window of 200 receipts
events.ndjson     # public host-event stream (materialized by QuickGate on behalf of Check-in: records + deletion markers)

Envelope: {v:1, id, op, args, createdAt, ttlMs?, reply?, device?} — receipts echo id with status ∈ recorded|duplicate|rejected|failed|unsupported|expired. Full contract: docs/api.md · machine-readable: docs/contracts/quickgate-api-v1.json (the op face is enforced against src/ops.ts by a consistency test).

Clients included in tools/: zero-dependency node CLI (ping/send/run/events/exec/fast), a PowerShell script (-Exec kernel route, -Fast broadcast) and restart-siyuan.bat (one-click safe restart after deploying). Quicker subprograms use the same envelope.

MCP for AI assistants

src/mcp/ exposes all 39 ops as MCP tools over stdio — AI clients can run SiYuan commands, log check-ins, record contacts interactions and execute controlled workflows, including the Lv ecosystem actions that are outside SiYuan's built-in MCP surface. See the MCP guide for the protocol and safety model.

• 22 read-only tools by default; write tools stay hidden until LV_MCP_WRITE=1 (calls to hidden tools are honestly refused)

• plugin.api / workflow.execute additionally carry the destructiveHint annotation

• All QuickGate-side defenses still apply: confirm dialogs, blacklist, audit log, plugin.api allowlist

v0.9.3 fixes the repeated disabled notice during plugin reloads, adds capture target previews and confirmation, checks public installation and invocation conditions, and validates form/MCP inputs. Validated invocation examples can be copied without dispatching a request. See the changelog for details and the contacts v2 limitation.

{ "mcpServers": { "lv-quickgate": {
    "command": "node",
    "args": ["<repo>/src/mcp/main.ts"],
    "env": { "SIYUAN_TOKEN": "<token>" }
} } }

Built-in SiYuan Agent integration (automatic, no config)

On SiYuan ≥3.8.6 the plugin registers three capabilities natively with the built-in AI Agent via siyuan.agent.registerCapability: quickgate_ping (health), quickgate_discover (diary notebook + inbox discovery) and quickgate_capture (append a line to today's daily note). Verified live on the Agent's model-facing tool list (/api/ai/lsCapabilities) — nothing to configure. Alternatively, point the Agent's external-MCP settings at this repo's MCP stdio server for the full 27-tool surface — full guide (field-level ai.mcp.servers setup + approval policy): docs/agent-integration.md.

Safety

• Bridge is off by default; commands.run shows a confirm dialog (30s timeout = deny) and everything is audited.

• plugin.api raw pass-through is off by default with an allowlist (window-bridge mapping comes from the ecosystem manifest, not hard-coded).

• The hub only consumes publicly registered capabilities and public bridge methods. It never reads other plugins' private storage.

• The event stream is append-only; deletions are marker rows paired by idempotency key. High-frequency heartbeat events (analytics-updated) are explicitly excluded from materialization (D-0011).

Status & roadmap

Kernel-runtime verification (M0 spike ①–⑪) is tracked in docs/WALKTHROUGH.md; roadmap in docs/ROADMAP.md; decision log in docs/DECISIONS.md (D-0001–D-0015).

Development

corepack pnpm install
corepack pnpm check   # tsc + svelte-check
corepack pnpm accept  # unit tests + MCP protocol smoke (6 protocol checks; live bridge.ping adds one environment-dependent check)
corepack pnpm build   # dist/ + package.zip
corepack pnpm make-link  # symlink into your workspace for dev

After deploying, restart SiYuan (or double-click tools/restart-siyuan.bat), then run:

• corepack pnpm run verify:restart (add SIYUAN_LOG=<workspace>/temp/siyuan.log for the log-growth readout) — full acceptance dataset: bridge e2e latency, kernel-route ops, event materialization counts, broadcast liveness, v1.5 fast-path latency, MCP kernel-route, kernel log growth.

• corepack pnpm run verify:bg — 7-check background walkthrough (including the "frontend bundle discriminator": after deploying index.js you must fully quit & restart SiYuan, and this check should pass).

License: MIT · Author: @ai68298100