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 (7 plugins, maturity × installed version), sanitized diagnostics, daily-note notebook + inbox auto-discovery

• 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 Sisyphus MCP

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.

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.

• 14 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

{ "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