mirror of
https://github.com/Finesssee/ProxyPilot.git
synced 2026-11-18 18:04:20 +00:00
docs: add ProxyPilot overview and update memory docs
This commit is contained in:
@@ -33,6 +33,7 @@ docs/*
|
||||
!docs/desktop-ui-spec.md
|
||||
!docs/windows-ui-spec.md
|
||||
!docs/memory.md
|
||||
!docs/proxypilot.md
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
GEMINI.md
|
||||
|
||||
+6
-3
@@ -41,9 +41,7 @@ The session key is chosen in this order:
|
||||
|
||||
- Dropped items are appended as JSONL events (`dropped_chat` / `dropped_responses`)
|
||||
- Retrieval is a lightweight keyword scorer over the last ~2MB of stored events
|
||||
- Up to 8 snippets (~6k chars) are injected:
|
||||
- `/v1/responses`: appended to `instructions`
|
||||
- `/v1/chat/completions`: appended to the first system message, or prepended as a new system message
|
||||
- Up to 8 snippets (~6k chars) are injected by appending to the **last user message** (best-effort).
|
||||
|
||||
## Environment variables
|
||||
|
||||
@@ -80,3 +78,8 @@ Packed block format:
|
||||
- `<pinned>` from `pinned.md`
|
||||
- `<anchor>` from `summary.md`
|
||||
- `<todo>` from `todo.md`
|
||||
|
||||
## Text normalization
|
||||
|
||||
Some clients (notably PowerShell `ConvertTo-Json`) can store TODO/pinned state with escaped sequences like `\\n` / `\\u2019`.
|
||||
CLIProxyAPI normalizes common escape sequences when reading/writing `todo.md`, `pinned.md`, and `summary.md` so the injected state stays readable.
|
||||
|
||||
@@ -0,0 +1,132 @@
|
||||
# ProxyPilot (CLIProxyAPI Desktop + Agentic CLI Hardening)
|
||||
|
||||
ProxyPilot is the desktop-facing packaging/branding for running and managing a local `CLIProxyAPI` instance, with extra compatibility features for agentic CLIs (Factory Droid, Codex CLI, Warp).
|
||||
|
||||
This doc summarizes the current behavior and the key “quality of life” features added recently.
|
||||
|
||||
## What’s included
|
||||
|
||||
- **ProxyPilot tray app (Windows)** to start/stop/restart the proxy, open UI, open logs, and toggle autostart.
|
||||
- **Droid/Factory reliability fixes** so tool calls are emitted consistently and errors show up even for strict streaming clients.
|
||||
- **Agentic prompt-budget middleware** to prevent upstream “prompt too long” failures.
|
||||
- **Long-session memory** with anchored summaries + persistent TODO + pinned state (local disk).
|
||||
|
||||
## Quickstart (Windows)
|
||||
|
||||
### Build the proxy
|
||||
|
||||
- `.\scripts\build-cliproxyapi.ps1`
|
||||
|
||||
### Build ProxyPilot tray app
|
||||
|
||||
- `.\scripts\build-cliproxytray.ps1`
|
||||
|
||||
Output:
|
||||
|
||||
- `bin\ProxyPilot.exe`
|
||||
|
||||
### Package (zip)
|
||||
|
||||
- `.\scripts\package-cliproxytray.ps1`
|
||||
|
||||
Output:
|
||||
|
||||
- `dist\ProxyPilot.zip`
|
||||
|
||||
### Package (self-extracting installer)
|
||||
|
||||
- `.\scripts\package-cliproxytray-installer.ps1`
|
||||
|
||||
Output:
|
||||
|
||||
- `dist\ProxyPilot-Setup.exe`
|
||||
|
||||
## Endpoints / health
|
||||
|
||||
- `GET /healthz` (no auth)
|
||||
- `GET /v1/models` (requires API key)
|
||||
|
||||
Example:
|
||||
|
||||
- `curl -H "Authorization: Bearer local-dev-key" http://127.0.0.1:<port>/v1/models`
|
||||
|
||||
## Agentic CLI compatibility (Droid / Codex / Warp)
|
||||
|
||||
### Tool-call correctness
|
||||
|
||||
For `/v1/responses` traffic from agentic CLIs, the proxy applies:
|
||||
|
||||
- Tool schema tightening (`additionalProperties:false`) to reduce invalid tool argument payloads.
|
||||
- Tool argument sanitization (strip unknown fields from tool call args).
|
||||
- Conversion of plain-text `<tool_call>{...}</tool_call>` blocks into structured Responses `function_call` items (when present).
|
||||
- If a Factory/Stainless client omits `tools`, the proxy injects a minimal `tools` set and forces `tool_choice:"auto"` so the model can emit tool calls.
|
||||
|
||||
### Streaming behavior (Factory/Stainless)
|
||||
|
||||
Some strict clients request `stream:true` but don’t reliably render JSON error bodies.
|
||||
For `factory-cli`/Stainless user agents, CLIProxyAPI may:
|
||||
|
||||
- Call upstream non-streaming and synthesize SSE so the client gets usable output/error text.
|
||||
|
||||
## Prompt budget (prevent “prompt too long”)
|
||||
|
||||
The `CodexPromptBudgetMiddleware` applies to agentic CLIs and will trim oversized requests:
|
||||
|
||||
- Keeps recent messages/input items
|
||||
- Truncates very large text blocks
|
||||
- Preserves tool call/result pairing to avoid “tool_use/tool_result mismatch” errors
|
||||
- Avoids disabling tools for Droid/Factory
|
||||
|
||||
Model-aware budget:
|
||||
|
||||
- If the chosen model has a small `context_length`, the middleware uses a smaller max body budget to reduce upstream failures.
|
||||
|
||||
Override:
|
||||
|
||||
- `CLIPROXY_AGENTIC_MAX_BODY_BYTES` (bytes, clamped)
|
||||
|
||||
## Long-session memory (anchored compression + retrieval)
|
||||
|
||||
See `docs/memory.md` for details.
|
||||
|
||||
Key points:
|
||||
|
||||
- Events are stored to `.proxypilot/memory/sessions/<sessionKey>/events.jsonl`
|
||||
- Anchored summary: `summary.md`
|
||||
- Pinned always-on state: `pinned.md`
|
||||
- Persistent TODO: `todo.md`
|
||||
|
||||
Session key precedence:
|
||||
|
||||
1. `X-CLIProxyAPI-Session`
|
||||
2. `X-Session-Id`
|
||||
3. JSON `prompt_cache_key`
|
||||
4. JSON `metadata.session_id` / `session_id`
|
||||
5. Hash fallback (auth+UA hashed; raw values not stored)
|
||||
|
||||
### Persistent TODO updates
|
||||
|
||||
You can update the TODO without touching files by sending:
|
||||
|
||||
- `X-CLIProxyAPI-Todo: <markdown>`
|
||||
|
||||
The proxy saves it to `todo.md` and strips the header before forwarding upstream.
|
||||
|
||||
## Autostart
|
||||
|
||||
ProxyPilot tray app can toggle “Launch on login”.
|
||||
On Windows this uses a per-user autostart mechanism (no admin required).
|
||||
|
||||
## Logs / diagnostics
|
||||
|
||||
Useful paths:
|
||||
|
||||
- `logs/cliproxyapi.out.log`
|
||||
- `logs/cliproxyapi.err.log`
|
||||
- `logs/v1-responses-*.log` / `logs/v1-chat-completions-*.log` (request logs, if enabled)
|
||||
|
||||
## Repo safety / public readiness
|
||||
|
||||
- `config.yaml`, auth files, logs, binaries, and memory state are gitignored.
|
||||
- Use `local-dev-key` only as an example; real keys should stay out of git.
|
||||
|
||||
Reference in New Issue
Block a user