llm-api-gateway-cli 1.0.4 → 1.0.5

package/README.en.md

@@ -0,0 +1,232 @@
+# LLM API Gateway CLI — English entry
+
+> **Language:** English (this page) · [中文（权威全文）](README.md)
+>
+> [`README.md`](README.md) is the authoritative, always-current document (Chinese, far more detail:
+> every flag, every API route, Docker publishing, troubleshooting).
+> This page is the English entry point: what the tool is, how to install it, and how to run it.
+
+A local toolbox for an **OpenAI-compatible LLM gateway** (default `http://127.0.0.1:9000`).
+It gives you five ways to talk to the gateway from your own machine, plus a task mode where the
+model actually reads and writes files in a directory you pick:
+
+| Mode | Entry point | What it does | Extra deps |
+| --- | --- | --- | --- |
+| 1 | `gateway-openai` (`cli-openai.js`) | OpenAI-compatible chat against `/v1/chat/completions` | `openai` SDK |
+| 2 | `gateway-anthropic` (`cli-anthropic.js`) | Anthropic-compatible calls against `/v1/messages` | `@anthropic-ai/sdk` |
+| 3 | `gateway-claude-code` (`cli-claude-code.js`) | Pipes through a locally installed `claude` CLI | local `claude` |
+| 4 + 5 | `gateway-web` (`server.js`) · `gateway-task` (`task-server.js`) | Local Web UI: chat, task mode and manual in one page | none |
+| 6 | `gateway-agent` (`cli-agent.js`) | Native agent CLI with tool calls (recommended) | none |
+
+Modes 4, 5 and 6 are plain Node.js with no additional dependencies — the two SDKs above are only
+needed by modes 1 and 2. Modes 4 and 5 run on **one port** (`3100`) as one service.
+
+## Requirements
+
+- **Node.js >= 18** (`node -v`). The installers check this and stop with a clear message; they never
+  install a runtime for you.
+- A gateway you can reach, plus an API key for it. There is no bundled model — this is a client.
+
+## Install
+
+Three routes, all producing the same artifact and the same commands.
+
+### A. One-liner script (macOS / Linux / WSL)
+
+```bash
+# Pin a release tag (recommended: the tag never moves)
+curl -fsSL https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/<version>/scripts/install.sh | bash
+
+# Or track the newest script from main (script and release contract may drift)
+curl -fsSL https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/main/scripts/install.sh | bash
+
+# Passing arguments through a pipe needs -s --
+curl -fsSL https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/<version>/scripts/install.sh \
+  | bash -s -- --version v1.0.0 --prefix "$HOME/.llm-api-gateway"
+```
+
+### B. One-liner script (Windows PowerShell 5.1 / 7)
+
+```powershell
+irm https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/<version>/scripts/install.ps1 | iex
+
+# Passing arguments needs the scriptblock form
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/<version>/scripts/install.ps1))) -Version v1.0.0 -DryRun
+```
+
+### C. npm
+
+```bash
+npm install -g llm-api-gateway-cli
+```
+
+The installers put everything under `~/.llm-api-gateway` (Windows: `$HOME\.llm-api-gateway`), add the
+bin directory to your `PATH`, are idempotent, and need no admin rights. Useful flags:
+`--prefix`, `--no-modify-path`, `--dry-run`, `--force`, `--base` (mirror).
+
+### Already have the sources
+
+```bash
+git clone https://github.com/boonya-hrgk/llm-api-gateway-cli
+cd llm-api-gateway-cli
+npm install
+npm link        # symlink, so edits take effect without reinstalling
+```
+
+You can also skip installing entirely inside the repo: `node cli-agent.js`, `node server.js`.
+
+## First-time setup
+
+You do **not** need to hand-write `.env` any more. Either run the guided setup:
+
+```bash
+gateway-agent setup                                    # asks for gateway URL, then the key (hidden input)
+gateway-agent setup --base-url http://127.0.0.1:9000 --key sk-xxx   # non-interactive
+```
+
+or set the key from the Web UI (`Settings -> gateway key`) after starting the service — the server
+**starts without a key on purpose**, so the page is reachable and you have somewhere to paste it.
+
+The key is written to `~/.llm-api-gateway-cli/credentials.json` (owner-readable only) and is
+**never stored in `config.json`**. Sources are resolved in this order, first hit wins:
+
+1. `--key sk-xxx` on the command line
+2. environment variables: `GATEWAY_KEY`, `SK`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`
+3. `credentials.json` (what the UI / `config set key` writes)
+4. `.env` in the install directory, then in the current working directory
+
+When the key comes from the environment, `credentials.json` is ignored — the startup banner always
+prints which source is in effect, so you never have to guess.
+
+```bash
+gateway-agent config set baseUrl http://127.0.0.1:9000
+gateway-agent config set model qwen3:8b
+gateway-agent config list            # every value and where it comes from
+```
+
+## Quick start
+
+### Command line
+
+```bash
+gateway-agent -p "explain this stack trace"     # one-shot
+gateway-agent -i                               # interactive REPL
+gateway-agent                                   # bare command: asks chat/task, CLI/web
+```
+
+Bare `llm-api-gateway-cli` (or `gateway-agent`) with no arguments asks two questions — what to do
+(chat / task) and where to run it (terminal / Web UI) — instead of silently picking one. Passing
+`-p`, `-i`, or piping stdin skips the menu.
+
+Slash commands are available inside the REPL (`/help` lists them; the CLI REPL has 10 of them).
+
+### Web UI — one page, three tabs
+
+```bash
+gateway-web            # or: node server.js
+```
+
+| Page | URL | Notes |
+| --- | --- | --- |
+| Tab shell (recommended entry) | `http://127.0.0.1:3100/` | Chat / Task / Manual switch in one browser tab |
+| Chat panel | `http://127.0.0.1:3100/chat` | Pure conversation, no file system access |
+| Task panel | `http://127.0.0.1:3100/task` | Pick a directory, the model really reads/writes it |
+| Manual | `http://127.0.0.1:3100/manual` | Operation manual (Chinese) generated from the live command tables |
+
+The shell owns the single top bar (tabs, per-panel actions, theme, reload); panels are loaded
+lazily on first activation and keep their state when you switch away. `Alt+1/2/3` switches tabs.
+Each panel also opens standalone, which is what external systems embed.
+
+Useful flags: `--port`, `--host`, `--store <dir>`, `--mode manual|auto|plan`, `--max-steps`,
+`--allow-bash`, `--allow-remote-fs`, `--verbose` (`node server.js --help`).
+
+### Task mode in one minute
+
+1. Open the Task tab and pick a **working directory** — the model's file tools are confined to it.
+2. Describe the job, press `Enter`. The model lists directories, reads files and searches content.
+3. In **manual** mode every write shows an approval card first; click approve/reject (or `/approve`,
+   `/reject`). **auto** executes writes directly. **plan** gives the model read-only tools, writes a
+   plan document into `docs/` inside your working directory, and waits for you to confirm.
+4. `/stop` or the Stop button cancels the current run; other tasks keep going in the background.
+
+Tools the model can use: `list_dir`, `read_file`, `search_files`, `glob`, `grep`, `write_file`,
+`apply_patch`. `bash` exists but is **off by default** — enable it with `--allow-bash` (dangerous:
+in auto mode commands are not confirmed one by one). The task page has 14 slash commands; the manual
+page lists all of them side by side with the CLI.
+
+Task data is stored on disk by the server (not in the browser): `<data dir>/tasks/<id>.json` plus a
+model-side session per task. Default retention is a sliding **15 days / at most 20 tasks**.
+
+## Configuration and storage
+
+| Env var | Purpose |
+| --- | --- |
+| `GATEWAY_BASE_URL` | Gateway base URL (default `http://127.0.0.1:9000`) |
+| `GATEWAY_MODEL` | Default model (built-in default `qwen3:8b`) |
+| `GATEWAY_KEY` / `SK` | Gateway API key |
+| `WEB_PORT` / `TASK_WEB_PORT` | Web UI port (default `3100`) |
+| `TASK_MODE` | Default approval mode for new tasks: `manual` / `auto` / `plan` |
+| `TASK_MAX_STEPS` | Max model turns per task |
+| `TASK_STORE_DIR` | Where task records live |
+| `TASK_HISTORY_MAX_CHARS` | History budget sent to the model |
+| `TASK_SESSION_MAX_BYTES` | Cap for one task's model-side session file |
+| `LLM_GATEWAY_DATA_DIR` | Move the whole data root (config + credentials + tasks) |
+
+| File | Contents |
+| --- | --- |
+| `~/.llm-api-gateway-cli/config.json` | Settings (never the key) |
+| `~/.llm-api-gateway-cli/credentials.json` | The key, owner-readable only |
+| `~/.llm-api-gateway-cli/tasks/` | Task records + per-task sessions |
+
+Precedence everywhere is **command-line flag > environment variable > `.env` > `config.json` >
+built-in default**, and every surface (CLI, REPL, Web UI) reads and writes the same files.
+
+## Embedding and theming
+
+Any page can be embedded in another system, and you can hand it the host's background colour so it
+does not look pasted on:
+
+```
+http://127.0.0.1:3100/task?bg=%23f0f4ff     light host background
+http://127.0.0.1:3100/task?bg=%23111a2b     dark host background
+http://127.0.0.1:3100/task?bg=none          back to the page's own palette
+```
+
+The theme is derived from that one colour (panels, borders, text and accent all follow), and the
+theme switcher hides itself because the host now decides.
+
+## Docker
+
+A `Dockerfile`, `docker-compose.yml` and `docker.ps1` helper are included: one image containing the
+Web UI, with your project mounted as the agent's working directory and task history on a named
+volume. See the [Chinese README](README.md#docker-容器化部署) for the full walkthrough
+(`.\docker.ps1 up`, publishing to ACR / Docker Hub, troubleshooting).
+
+## Security notes
+
+- The API key stays on the server: the browser never receives it (the config endpoint returns a mask
+  and its source only).
+- Directory browsing, task records and the settings API are **only served when the service is bound
+  to loopback**. Binding `0.0.0.0` requires the explicit `--allow-remote-fs` flag.
+- The agent's sandbox is the working directory you picked: path traversal, absolute paths and
+  symlink escapes are rejected, and `bash` is off unless you pass `--allow-bash`.
+
+## Tests
+
+```bash
+npm test          # offline suite (no gateway needed)
+npm run test:all  # offline + tests that call a real gateway on 127.0.0.1:9000
+```
+
+## Where to read more
+
+- **`/manual`** in the running Web UI — install, first-time setup, task workflow, every slash command
+  on all three surfaces (its command tables are generated from `lib/commands.js` and
+  `public/task-slash.js`, so they cannot go stale).
+- [`README.md`](README.md) — the authoritative Chinese document: all flags, every API route, storage
+  internals, Docker publishing, FAQ.
+- [`docs/`](docs/) — iteration plans and release steps (Chinese).
+
+## License
+
+MIT

package/README.md

@@ -1,5 +1,8 @@
 # LLM API Gateway CLI 编程工具
 
+> 🌐 **English entry:** [`README.en.md`](README.en.md) —— 英文入口（是什么 / 怎么装 / 怎么跑）。
+> 本页是**权威全文**（中文，最全）：所有参数、全部接口、存储内部细节、Docker 发布与排错。
+
 验证 `llm-api-gateway`（`http://127.0.0.1:9000`）除了 Web 对话页 / SDK 之外，**CLI 方式同样可用**。多个脚本覆盖多种接入方言，其中**原生 Agent（`cli-agent.js`）是终端里干活的推荐方式** —— 自带工具循环，无需安装 Claude Code。
 
 | 脚本 | 模式 | 走网关的端点 | 依赖 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-api-gateway-cli",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "CLI 测试工具：验证 LLM API Gateway（http://127.0.0.1:9000）的 OpenAI / Anthropic / 原生 Agent / Claude Code 多种接入方式",
   "type": "module",
   "bin": {
@@ -43,6 +43,7 @@
     "cli-claude-code.js",
     "server.js",
     "task-server.js",
+    "README.en.md",
     "lib/",
     "!lib/.tasks/",
     "public/",