quicker-rpc-knowledge

name: quicker-rpc-knowledge description: >- Detailed QuickerRpc ecosystem knowledge: terminology (QuickerAgent Quicker action vs AI agent), architecture, named pipe, qkrpc serve, bootstrap, connectivity failure diagnosis. Use when qkrpc connection fails, PLUGIN_NOT_RUNNING, qkrpc_health/qkrpc_wait errors, serve 9477 unreachable, user asks how QuickerRpc or QuickerAgent works, or before telling the user to fix Quicker/plugin environment.

QuickerRpc knowledge

Domain reference for why qkrpc connects the way it does and what to do when it fails. For day-to-day tool usage see qkrpc; for writing actions see quicker-authoring.

Terminology (read first)

QuickerAgent action chain (in Quicker):

QuickerAgent.Start  (shared action, id 7d6999ed-93a1-4db0-9763-5405066199ac)
  └─ QuickerRpc_Run subprogram → QuickerRpc.Plugin.Launcher
       ├─ starts named-pipe RPC server
       └─ may launch quicker-agent.exe (desktop UI)

Bootstrap action (qkrpc auto-start when pipe missing):

• Action id: aa5917ad-1256-4c73-7022-08debe3efcbe
• URI: quicker:runaction:aa5917ad-1256-4c73-7022-08debe3efcbe?plugin (silent RPC only)

Full glossary: references/terminology.md

Architecture (one screen)

AI agent (Cursor / QuickerAgent chat / script)
    │
    ├─ MCP qkrpc_*  ──stdio──► qkrpc mcp ──┐
    ├─ HTTP ─────────────────► qkrpc serve :9477 ──┤
    └─ shell qkrpc ping/wait ──────────────────────┤
                                                   ▼
                              qkrpc.exe (pipe client)
                                                   │
                         named pipe QuickerRpc_Server_QRPC2026
                                                   ▼
                              QuickerRpc.Plugin (inside Quicker.exe)
                                                   ▼
                              Quicker UI thread / action services

• Pipe name: QuickerRpc_Server_QRPC2026 (QuickerRpcPipeNames.ServerPipe)
• Serve default: http://127.0.0.1:9477/health (long-lived pipe; used by QuickerAgent)
• Plugin must run inside Quicker — qkrpc alone cannot serve Quicker APIs without the pipe

Details: references/architecture.md

Connectivity failure — agent playbook

Step 1: One check, one wait (no probe loops)

QuickerAgent chat hard rule: on connectivity_failure, tell the user to check Quicker + plugin + serve — stop; no shell workaround unless user explicitly asks to fix the environment.

Step 2: Interpret error codes

Step 3: User checklist (plain language)

Tell the user to verify in order:

1. Quicker is running (Quicker.exe). If not, start Quicker first.
2. QuickerRpc plugin loaded — run QuickerAgent action once, or open shared action aa5917ad-…, or run quicker:runaction:aa5917ad-1256-4c73-7022-08debe3efcbe?plugin.
3. QuickerAgent / dev: if tools fail but Quicker is OK, ensure qkrpc serve on :9477 (sidebar "重新检测" or GET http://127.0.0.1:9477/health).
4. After repo plugin/CLI changes: maintainer runs pwsh ./build.ps1 -t (hot-reload DLL + restart serve) — not the chat agent's job unless user asks.

Step 4: Bootstrap behavior (why auto-start sometimes fails)

• qkrpc may launch quicker:runaction:…?plugin when pipe missing and Quicker is running.
• Skipped when Quicker process not found (avoids duplicate popups).
• Cooldown ~120s per process between bootstrap launches (QuickerRpcBootstrapPolicy).
• Bootstrap waits up to 12s for pipe; qkrpc wait default up to 120s.

Full decision tree: references/connectivity.md

QuickerRpc_Run start modes (quicker_in_param)

Key paths & IDs

Agent capability matrix

Related skills

Human docs

• README.md — install, architecture
• docs/agent-mcp-integration.md — third-party MCP
• docs/cli-commands.md — CLI reference
• AGENTS.md — repo agent rules