Skip to content

Repository navigation

quick-start.md

Latest commit

 

History

History
209 lines (152 loc) · 9.95 KB

quick-start.md

File metadata and controls

209 lines (152 loc) · 9.95 KB
Raw

🚀 PatchCat Quick Start Guide

Positioning: Deterministic AI Workflow Engine · Interactive Playground

Welcome to PatchCat! PatchCat is both a production-grade deterministic AI workflow orchestration engine and a white-box interactive playground designed for AI engineers, architects, and learners. In this guide, you will learn how to orchestrate workflows in under 5 minutes—whether you have an API key or want to test DAG mechanics completely offline.

📋 What You Will Learn

By the end of this quickstart tutorial, you will know how to:

  1. Launch PatchCat in your local browser environment.
  2. Explore DAG topology and slot resolution offline without an API key.
  3. Connect an LLM provider (Google Gemini, DeepSeek, OpenAI, or local Ollama) using your own API Key (BYOK).
  4. Execute a pre-built industrial workflow (Customer Support Intent Classification & VIP Logistics Routing).
  5. Inspect real-time token streams, DeepSeek reasoning chains, and 3-tier security execution logs.
  6. Build, customize, and experiment with your own visual DAG workflows.

🛠️ Prerequisites

Before you start, make sure you have:

  • Node.js >= 18.0.0
  • npm >= 9.0.0 or pnpm
  • A modern browser (Chrome, Edge, Firefox, Safari)
  • (Optional, for live LLM execution) An API Key from any supported provider (not needed for offline playground testing):

📦 Step 1: Launch PatchCat

1. Clone the repository

git clone https://github.com/GuoBug/PatchCat.git
cd PatchCat

2. Install dependencies

npm install

3. Start the development server

npm run dev

Open your browser and navigate to http://localhost:5173. You will see the PatchCat Visual Workflow Canvas.

🔑 Step 2: Configure Your Model Provider (BYOK)

PatchCat operates with a 100% Client-Only Privacy Architecture: your API Keys are stored exclusively in your browser's LocalStorage and connect directly to model providers. They are never transmitted to any intermediary backend.

PatchCat Client-Only Privacy Architecture

  1. In the top navigation bar, click the API Key button (or the key icon).
  2. Select your preferred provider from the left sidebar (e.g., Google Gemini).
  3. Paste your API Key into the input field.
  4. Click 测试连通性 (Test Connection):
    • PatchCat automatically tests the endpoint and fetches all available chat models (e.g., gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash).
  5. Click ← Back to Canvas in the top-left corner. Your provider is now active and marked with a green indicator in the header!

Tip

Recommended Model: For Google Gemini, we recommend gemini-2.5-flash for instant response speeds and high availability on the free tier.

🎯 Step 3: Run Your First Workflow

Upon initial launch, PatchCat pre-loads the Customer Support Routing workflow template.

Understanding the Pipeline Topology

This workflow consists of 5 canonical nodes:

PatchCat Customer Support Routing Workflow Topology

Executing the Workflow

  1. Click the blue ▶ Run Workflow button in the top right corner.
  2. Watch the execution in real time:
    • Nodes transition from idle ➔ running (with live spinner) ➔ success (with latency badge).
    • The LLM node streams generated tokens live on the canvas.
    • The JavaScript Code node extracts the intent (物流催单), evaluates urgency (4分), and routes the ticket to the 🚀 物流专线极速客服队列 (Logistics VIP).
  3. Click on any node to open the Right Property Inspector Panel and inspect its input parameters, prompt template, or formatted JSON output.

🔍 Step 4: Inspect Telemetry & 3-Tier Security Logs

PatchCat includes an enterprise-grade execution logging engine integrated directly into the Settings Center.

  1. Click the Settings button in the top navigation bar, then switch to the Execution Logs (运行日志) tab.
  2. Switch between the 3 Configurable Log Levels:
    • 概要 (Summary): Macro workflow lifecycle, HTTP status codes, latency, and system alerts.
    • 详细 (Detailed): Node IDs, runtime parameters (model, temperature, max_tokens), and DAG layer wave scheduling.
    • 开发 (Development): Full Prompt inputs, variable resolution payloads, and LLM generated responses.
  3. Strict Zero-Leakage Guarantee: Notice that even in Development mode, all API keys (sk-***, AIzaSy***), Bearer tokens, and passwords are automatically masked with ***[MASKED]***.
  4. Tools in the Console:
    • Filter by Type: All, System, Request, Node, Error, Security.
    • Search: Filter logs in real time by keywords or Node IDs.
    • Expand Payload: Click 详情 Payload to inspect formatted JSON trees and copy with one click.
    • Export: Click 导出 to download logs as .json or .txt reports.

🎨 Step 5: Build a Custom Workflow from Scratch

Ready to create your own pipeline? Follow these simple steps:

1. Add Nodes

Click the + Add Node dropdown in the top header and add any of the standard nodes:

  • Input: Define custom input variables and types (string, number, boolean, json).
  • Prompt: Write prompt templates with dynamic variable slots using {{nodeId.property}}.
  • LLM: Select models (Gemini, DeepSeek, OpenAI), configure temperature, and set system prompts.
  • Code: Write custom JavaScript transformation scripts with inputs and console.log capture.
  • Output: Format and present final workflow outputs.

2. Connect Edges

Click and drag from a source node's right handle (output port) to a target node's left handle (input port).

3. Dynamic Variable Resolution Syntax

PatchCat supports powerful Mustache-style variable interpolation:

// Simple variable reference
{{input_node.user_query}}

// Nested property and array access
{{llm_node.response.items[0].name}}

// Safe fallback default value (prevents runtime failure if empty)
{{input_node.optional_vip_tag | "STANDARD_USER"}}

4. Topology Validation & Safety

PatchCat's engine utilizes Kahn's Topological Algorithm:

  • Automatic Parallel Waves: Nodes on the same dependency layer execute concurrently via Promise.all.
  • Cycle Detection: If you accidentally connect a cyclic loop ($A \to B \to A$), PatchCat detects the cycle in milliseconds, highlights the affected nodes in red, and presents an alert banner to prevent infinite loops.

🧪 Step 6: Zero-Key Interactive Playground

Beyond serving as a production-grade workflow runtime, PatchCat is designed as an interactive AI playground for developers, researchers, and learners to inspect and experiment with deterministic orchestration primitives without friction:

1. Validate Flow Only (Zero-Key Simulation)

Without entering any API keys, click Run Workflow and choose Validate Flow Only (Skip LLM):

  • Safely bypasses remote LLM network calls while verifying Kahn topological ordering, concurrency waves, and port bindings;
  • Validates Mustache slot parsing (e.g. {{nodeId.property}}) and fallback defaults;
  • Traces real-time node state transitions and downstream data flow.

2. Cycle Deadlock Chaos Testing

  • Try drawing a reverse edge from node B back to node A on the canvas to create a loop;
  • Click Run and witness the scheduler intercept the cycle in milliseconds, highlight the offending nodes in red, and block deadlocks before execution starts.

3. Local Deterministic Contract Test Suite

Run the built-in contract assertion suite locally to explore state machines and structured schema guarantees:

# Run all deterministic contract tests
npm test

# Run real LLM structured output benchmark
npm run test:ab

❓ Troubleshooting & FAQs

Q1: I encounter HTTP 503 (Model Overloaded) with Google Gemini.

Cause: Google's free tier on preview or experimental models (e.g., gemini-3.7-flash) occasionally experiences global traffic spikes.
Solution: Click the LLM node, open the Property Panel, and switch the model dropdown to gemini-2.5-flash or gemini-2.0-flash, which offer stable high throughput. PatchCat also includes a built-in 1.5s automatic retry mechanism.

Q2: How does cross-vendor model compatibility work?

If a preset workflow was created with gpt-4o-mini, but your active provider is Google Gemini, PatchCat's resolveTargetModel engine automatically remaps the request to gemini-2.5-flash, eliminating cross-vendor 400/404 errors.

Q3: How do I run unit tests?

PatchCat features 100% automated test coverage across DAG sorting, variable resolving, LLM client streaming, and logger sanitization:

npm test

📚 Next Steps