docs(extension): expand AnythingLLM Workspaces README
**Motivations:** - Clear usage: palette, Dev tools panel, install, troubleshooting **Root causes:** - N/A **Correctifs:** - N/A **Evolutions:** - README sections: requirements, configuration, commands, SSH note, API refs **Pages affectées:** - extensions/anythingllm-workspaces/README.md
This commit is contained in:
parent
dce376f2b7
commit
615958469d
@ -1,52 +1,102 @@
|
|||||||
# AnythingLLM Workspaces (VS Code / Cursor extension)
|
# AnythingLLM Workspaces (VS Code / Cursor)
|
||||||
|
|
||||||
Extension for the **AnythingLLM developer API**, optional **local repos API** (`repos-devtools-server`), and a **dev tools panel** for slash-style commands.
|
Extension that talks to the **AnythingLLM developer HTTP API** (list/create workspaces, open the UI in a browser). Optionally uses a **local repos HTTP service** (`repos-devtools-server`) to clone or open Git folders under a configured root, from a **Dev tools** webview panel.
|
||||||
|
|
||||||
## Prerequisites
|
## Features
|
||||||
|
|
||||||
- AnythingLLM reachable at your public base URL (e.g. `https://ia.enso.4nkweb.com/anythingllm`).
|
| Area | What it does |
|
||||||
- An **API key** created in AnythingLLM: **Settings → API Keys**.
|
|------|----------------|
|
||||||
|
| AnythingLLM | List workspaces, open one in the browser, open the web UI. |
|
||||||
|
| Workspace ensure | If no workspace matches a repo folder name, create it via `POST /api/v1/workspace/new`. |
|
||||||
|
| Local repos API | Clone (`branch` **test** by default), list git folders, resolve paths — requires `repos-devtools-server`. |
|
||||||
|
|
||||||
**Do not** use the **nginx Bearer secret** for `/ollama/` (see `deploy/nginx/README-ia-enso.md`). That value is only for the Ollama reverse proxy. AnythingLLM validates API keys against its **own** database; a wrong secret yields `403` with `{"error":"No valid api key found."}`.
|
## Requirements
|
||||||
|
|
||||||
For **clone / repos-list / repos-load**, run **`services/repos-devtools-server`** on the host that owns the clone root (e.g. `192.168.1.164` with `REPOS_DEVTOOLS_ROOT=/home/ncantu/code`). The extension calls this API over HTTP (default `http://127.0.0.1:37140` when your editor runs on that same host or via port-forward).
|
1. **AnythingLLM** reachable at a public base URL (example: `https://ia.enso.4nkweb.com/anythingllm`).
|
||||||
|
2. An **API key** from AnythingLLM: **Settings → API Keys**.
|
||||||
|
|
||||||
|
**Important:** Do **not** put the **nginx Bearer secret** used for `/ollama/` here (see `deploy/nginx/README-ia-enso.md`). AnythingLLM only accepts keys stored in its own app; a wrong value returns `403` and `{"error":"No valid api key found."}`.
|
||||||
|
|
||||||
|
3. For **clone / repos-list / repos-load** commands: run **`repos-devtools-server`** on the machine that owns the clone directory (see `../../services/repos-devtools-server/README.md`). Default URL from the editor: `http://127.0.0.1:37140`. If Cursor connects over **SSH** to that host, `127.0.0.1` is the remote machine — no port forward needed. If the editor runs on another PC, set `anythingllm.reposApiBaseUrl` to a tunnel or the server’s reachable address.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
- **From source:** open `extensions/anythingllm-workspaces` in VS Code / Cursor, **Run → Start Debugging** (Extension Development Host).
|
||||||
|
- **From VSIX:**
|
||||||
|
`npm install && npm run compile && npx @vscode/vsce package`
|
||||||
|
then **Extensions → … → Install from VSIX…** and pick `anythingllm-workspaces-*.vsix`.
|
||||||
|
|
||||||
|
After install or upgrade, run **Developer: Reload Window** if commands are missing.
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
| Setting | Description |
|
Open **Settings**, search for **AnythingLLM**, or edit **User** `settings.json`:
|
||||||
|--------|-------------|
|
|
||||||
| `anythingllm.baseUrl` | Base URL without trailing slash (default matches `deploy/nginx/README-ia-enso.md`). |
|
|
||||||
| `anythingllm.apiKey` | Secret from AnythingLLM **Settings → API Keys** (optional leading `Bearer ` is stripped). Use **User** settings. |
|
|
||||||
| `anythingllm.reposApiBaseUrl` | `repos-devtools-server` base URL (no trailing slash), default `http://127.0.0.1:37140`. |
|
|
||||||
| `anythingllm.reposApiToken` | Same value as `REPOS_DEVTOOLS_TOKEN` on the server. **User** settings. |
|
|
||||||
|
|
||||||
## Commands (palette)
|
| Key | Description |
|
||||||
|
|-----|-------------|
|
||||||
|
| `anythingllm.baseUrl` | AnythingLLM public base URL, **no** trailing slash. |
|
||||||
|
| `anythingllm.apiKey` | API key from AnythingLLM (a leading `Bearer ` prefix is stripped if present). |
|
||||||
|
| `anythingllm.reposApiBaseUrl` | `repos-devtools-server` base URL, no trailing slash (default `http://127.0.0.1:37140`). |
|
||||||
|
| `anythingllm.reposApiToken` | Same secret as `REPOS_DEVTOOLS_TOKEN` on the server. |
|
||||||
|
|
||||||
- **AnythingLLM: List workspaces** — `GET /api/v1/workspaces`, then open the chosen workspace in the browser.
|
Use **User** settings so secrets are not committed with a workspace.
|
||||||
- **AnythingLLM: Open web UI** — Opens the AnythingLLM base URL.
|
|
||||||
- **AnythingLLM: Dev tools panel** — Webview: enter commands, **Run**, read JSON/text **Response**.
|
|
||||||
|
|
||||||
## Dev tools panel — command lines
|
## Commands (Command Palette)
|
||||||
|
|
||||||
One command per line:
|
Open the palette: **Ctrl+Shift+P** (Windows / Linux) or **Cmd+Shift+P** (macOS).
|
||||||
|
|
||||||
|
| Title in palette | Command ID | Action |
|
||||||
|
|------------------|------------|--------|
|
||||||
|
| **AnythingLLM: List workspaces** | `anythingllm.listWorkspaces` | Calls `GET /api/v1/workspaces`, pick a workspace, open it in the browser. |
|
||||||
|
| **AnythingLLM: Open web UI** | `anythingllm.openWebUi` | Opens `anythingllm.baseUrl` in the browser. |
|
||||||
|
| **AnythingLLM: Dev tools panel** | `anythingllm.openDevToolsPanel` | Opens the Dev tools webview (see below). |
|
||||||
|
|
||||||
|
## Dev tools panel
|
||||||
|
|
||||||
|
### How to open it
|
||||||
|
|
||||||
|
1. **Ctrl+Shift+P** / **Cmd+Shift+P**
|
||||||
|
2. Type **AnythingLLM: Dev tools panel** (or `dev tools`, `anythingllm`).
|
||||||
|
3. **Enter**
|
||||||
|
|
||||||
|
A side editor tab opens with:
|
||||||
|
|
||||||
|
- A **Commands** text area (one command per line)
|
||||||
|
- **Run** — execute all non-empty lines in order
|
||||||
|
- **Clear output**
|
||||||
|
- **Response** — JSON or text from the server / API, or `ERROR: …`
|
||||||
|
|
||||||
|
Settings are read **when you click Run**, so you can change `baseUrl` or tokens without reopening the panel.
|
||||||
|
|
||||||
|
### Command lines
|
||||||
|
|
||||||
| Line | Behaviour |
|
| Line | Behaviour |
|
||||||
|------|-----------|
|
|------|-----------|
|
||||||
| `/repos-clone <git-url>` | `POST /repos-clone` — clone into `REPOS_DEVTOOLS_ROOT`, branch **`test`** (override with JSON only via API, not this line). |
|
| `/repos-clone <git-url>` | `POST /repos-clone` — clone into `REPOS_DEVTOOLS_ROOT`, branch **`test`**. |
|
||||||
| `/repos-clone-sync <url>` | Clone + ensure AnythingLLM workspace named like the repo folder + **Open folder** + open workspace in browser. |
|
| `/repos-clone-sync <url>` | Same as clone, then ensure an AnythingLLM workspace with the **same name as the repo folder**, **Open folder** in the editor, open that workspace in the browser. |
|
||||||
| `repos-list` or `/repos-list` | `GET /repos-list` — cloned git directories under the root. |
|
| `repos-list` or `/repos-list` | `GET /repos-list` — git repositories under the server root. |
|
||||||
| `/repos-load <name>` | Verify repo folder + **Open folder** in the editor. |
|
| `/repos-load <folder-name>` | `POST /repos-load` — verify folder + **Open folder**. |
|
||||||
| `/repos-load-sync <name>` | Open folder + ensure workspace + browser. |
|
| `/repos-load-sync <name>` | Same as load + ensure workspace + browser. |
|
||||||
| `/workspace-load <name>` | Ensure workspace exists (`GET /workspaces` then `POST /workspace/new` if missing) + browser. |
|
| `/workspace-load <name>` | List workspaces; if none matches by **name** or **slug**, create via API; then open browser. |
|
||||||
| `help` | Short built-in help text. |
|
| `help` or `/help` | Print built-in help in **Response**. |
|
||||||
|
|
||||||
**Workspace matching:** name or slug must equal the folder/repo name you use (exact string match on `name` or `slug` from AnythingLLM). New workspaces are created with `POST /api/v1/workspace/new` and `{ "name": "<name>" }`.
|
**Workspace name:** Matching uses **exact** equality on AnythingLLM `name` or `slug` and the repo folder name you pass. Creation body: `{ "name": "<name>" }`.
|
||||||
|
|
||||||
**AnythingLLM “user”:** the developer API uses the **API key**; per-user workspace ownership follows AnythingLLM’s own multi-user rules — this extension does not impersonate a browser session.
|
**API key vs browser user:** The extension only uses the **developer API key**. Multi-user behaviour is defined by AnythingLLM for that key.
|
||||||
|
|
||||||
## Ollama
|
## Ollama
|
||||||
|
|
||||||
This extension does not call Ollama. For `https://ia.enso.4nkweb.com/ollama/v1`, use Cursor model settings and the nginx Bearer (see `deploy/nginx/README-ia-enso.md`).
|
This extension does **not** call Ollama. For OpenAI-compatible URLs such as `https://ia.enso.4nkweb.com/ollama/v1`, configure the editor’s model provider and use the nginx Bearer as documented in `deploy/nginx/README-ia-enso.md`.
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Symptom | Check |
|
||||||
|
|---------|--------|
|
||||||
|
| `403` / `No valid api key found` | Use an AnythingLLM **Settings → API Keys** value, not the Ollama nginx Bearer. |
|
||||||
|
| `401` on clone/list/load | `anythingllm.reposApiToken` must equal `REPOS_DEVTOOLS_TOKEN` on `repos-devtools-server`. |
|
||||||
|
| `ECONNREFUSED` / fetch failed | Server running? Correct `anythingllm.reposApiBaseUrl`? |
|
||||||
|
| Command palette has no AnythingLLM entries | Extension enabled? **Developer: Reload Window**. |
|
||||||
|
| Clone fails | Remote must expose branch **`test`** (or change branch via the HTTP API body, not the one-line panel command). |
|
||||||
|
|
||||||
## Build
|
## Build
|
||||||
|
|
||||||
@ -56,9 +106,13 @@ npm install
|
|||||||
npm run compile
|
npm run compile
|
||||||
```
|
```
|
||||||
|
|
||||||
Load the folder in VS Code / Cursor with **Run Extension** or install the packaged `.vsix` after `vsce package`.
|
Package: `npx @vscode/vsce package --allow-missing-repository` (Node 20+ recommended for current `vsce`).
|
||||||
|
|
||||||
## API reference
|
## API reference
|
||||||
|
|
||||||
- AnythingLLM: `server/endpoints/api/workspace/index.js` (e.g. `GET /v1/workspaces`, `POST /v1/workspace/new` under `/api`).
|
- AnythingLLM (upstream): Mintplex-Labs **anything-llm** — `server/endpoints/api/workspace/index.js` (routes under `/api`, e.g. `GET /v1/workspaces`, `POST /v1/workspace/new`).
|
||||||
- Local repos: `services/repos-devtools-server/README.md`.
|
- Local repos: `services/repos-devtools-server/README.md`.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user