@vincentbanana/bananacli 0.8.5 → 0.8.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +426 -0
- package/README.md +229 -133
- package/design-tokens.json +33 -0
- package/dist/agent/context.js +8 -3
- package/dist/agent/loop.js +71 -1
- package/dist/agent/retrieval.js +59 -0
- package/dist/agent/review.js +29 -0
- package/dist/cli/commands.js +211 -2
- package/dist/cli/continuation.js +14 -0
- package/dist/cli/repl.js +49 -16
- package/dist/cli/templates.js +23 -0
- package/dist/config/config.js +161 -21
- package/dist/config/project-trust.js +52 -0
- package/dist/config/version.js +3 -0
- package/dist/index.js +36 -5
- package/dist/providers/reasoning.js +7 -8
- package/dist/server/ui-server.js +228 -30
- package/dist/session/backups.js +17 -4
- package/dist/session/phases.js +51 -0
- package/dist/session/store.js +49 -10
- package/dist/session/trace.js +31 -0
- package/dist/session/verify.js +60 -0
- package/dist/tools/fs.js +34 -10
- package/dist/tools/index.js +11 -1
- package/dist/tools/memory.js +121 -0
- package/dist/tools/plugins.js +3 -2
- package/dist/tools/todo.js +25 -1
- package/dist/tools/ui.js +41 -0
- package/dist/ui/app.js +558 -67
- package/dist/ui/index.html +5 -1
- package/dist/ui/style.css +237 -240
- package/dist/util/ui-audit.js +192 -0
- package/docs/ab-testing.md +26 -0
- package/docs/assets/README.md +30 -0
- package/docs/assets/build-real-en.png +0 -0
- package/docs/assets/build-real.png +0 -0
- package/docs/assets/changes-real-en.png +0 -0
- package/docs/assets/changes-real.png +0 -0
- package/docs/assets/cli.png +0 -0
- package/docs/assets/cli.svg +29 -0
- package/docs/assets/demo-en.gif +0 -0
- package/docs/assets/demo-zh.gif +0 -0
- package/docs/assets/demo.png +0 -0
- package/docs/assets/demo.svg +59 -0
- package/docs/assets/gui-real-en.png +0 -0
- package/docs/assets/gui-real.png +0 -0
- package/docs/assets/gui.png +0 -0
- package/docs/assets/gui.svg +61 -0
- package/docs/assets/review-real-en.png +0 -0
- package/docs/assets/review-real.png +0 -0
- package/docs/assets/review.png +0 -0
- package/docs/assets/review.svg +39 -0
- package/docs/assets/social-preview.png +0 -0
- package/docs/assets/social-preview.svg +35 -0
- package/docs/design/README.md +43 -0
- package/docs/design/accessibility.md +32 -0
- package/docs/design/checklist.md +25 -0
- package/docs/design/components.md +41 -0
- package/docs/design/content.md +31 -0
- package/docs/design/data-display.md +33 -0
- package/docs/design/examples/README.md +35 -0
- package/docs/design/examples/bad/big-radius.css +4 -0
- package/docs/design/examples/bad/emoji.tsx +3 -0
- package/docs/design/examples/bad/glass.css +5 -0
- package/docs/design/examples/bad/gradient-hero.css +11 -0
- package/docs/design/examples/bad/heavy-shadow.css +3 -0
- package/docs/design/examples/bad/neon.css +8 -0
- package/docs/design/examples/good/pricing-page.css +74 -0
- package/docs/design/examples/good/pricing-page.html +31 -0
- package/docs/design/forms.md +32 -0
- package/docs/design/layout.md +32 -0
- package/docs/design/motion.md +33 -0
- package/docs/design/principles.md +33 -0
- package/docs/design/refs/github-primer.md +4 -0
- package/docs/design/refs/govuk.md +4 -0
- package/docs/design/refs/linear.md +4 -0
- package/docs/design/refs/notion.md +4 -0
- package/docs/design/refs/stripe.md +4 -0
- package/docs/design/states.md +34 -0
- package/docs/design/tokens.md +39 -0
- package/docs/design/typography-spacing.md +37 -0
- package/docs/failures.md +75 -0
- package/docs/prompt-versions.md +10 -0
- package/package.json +9 -4
package/README.en.md
ADDED
|
@@ -0,0 +1,426 @@
|
|
|
1
|
+
# BananaCLI + BananaGUI
|
|
2
|
+
|
|
3
|
+
English | [中文](README.md)
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+

|
|
7
|
+

|
|
8
|
+

|
|
9
|
+
|
|
10
|
+
> [!IMPORTANT]
|
|
11
|
+
> **AI-generated code disclosure**
|
|
12
|
+
> Most code and docs in this repository were generated by AI, with human review,
|
|
13
|
+
> automated tests, and security checks. It is not a fully human-audited codebase.
|
|
14
|
+
> Review before production use. See [AI_DISCLOSURE.md](AI_DISCLOSURE.md).
|
|
15
|
+
|
|
16
|
+
A multi-provider AI agent for the terminal, with a local GUI. It can read and write files, run commands, search code, and browse the web. Conversations are saved automatically and can be resumed at any time.
|
|
17
|
+
|
|
18
|
+
## 30-second overview
|
|
19
|
+
|
|
20
|
+
> GUI / Review are real screenshots from a running `banana --ui`; CLI is schematic.
|
|
21
|
+
|
|
22
|
+
[](https://github.com/Vincentwen12/BananaGUI/blob/main/docs/assets/demo-en.gif)
|
|
23
|
+
|
|
24
|
+

|
|
25
|
+
|
|
26
|
+

|
|
27
|
+
|
|
28
|
+
| CLI |
|
|
29
|
+
|---|
|
|
30
|
+
|  |
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
____ _
|
|
34
|
+
| __ ) __ _ _ __ __ _| |__ __ _ _ __
|
|
35
|
+
| _ \ / _` | '_ \ / _` | '_ \ / _` | '_ \
|
|
36
|
+
| |_) | (_| | | | | (_| | |_) | (_| | | | |
|
|
37
|
+
|____/ \__,_|_| |_|\__,_|_.__/ \__,_|_| |_|
|
|
38
|
+
|
|
39
|
+
BananaCLI v0.8.7 · terminal + GUI
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- **No frontend framework**: the CLI uses Node built-ins only; runtime dependencies are `ws` and `@lydell/node-pty` (prebuilt native module).
|
|
43
|
+
- **Hand-written agent loop**: tool calling, tool registry, permissions, and context compaction live in this repository.
|
|
44
|
+
- **Multi-provider**: OpenAI-compatible APIs (DeepSeek / Moonshot / Qwen / Gemini / OpenRouter / Ollama …) and native Anthropic, with SSE streaming.
|
|
45
|
+
- **Persistent sessions**: every turn is saved under `~/.banana/sessions/`; use `/list` and `/use` to switch.
|
|
46
|
+
- **Plan / Build modes**: Plan is read-only and produces a plan for approval; approving it switches to Build and executes the checklist.
|
|
47
|
+
- **Project rules**: `AGENT.md` records environment, paths, commands, and constraints so the agent does not re-probe them.
|
|
48
|
+
- **Diff before write, undo after**: file writes show exact added/removed lines; `/undo` restores the previous turn.
|
|
49
|
+
- **Task list**: `todo_write` / `todo_read`, persisted with the session; the GUI has a task dock and plan card.
|
|
50
|
+
- **Multimodal and extensible**: `/image` attaches screenshots; scripts in `.banana/tools/` register custom tools; cost is estimated per token.
|
|
51
|
+
- **UI constraints**: shared design tokens plus `npm run ui:check` to catch gradients, glassmorphism, oversized radii, purple AI palettes, and emoji.
|
|
52
|
+
|
|
53
|
+
## GUI
|
|
54
|
+
|
|
55
|
+
Same core, two interfaces. Add `--ui` to the CLI:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
banana --ui # open the GUI
|
|
59
|
+
banana --ui --no-open # start the server without opening a browser
|
|
60
|
+
npm install -g @vincentbanana/banana-gui && banana-gui # or install the standalone GUI package
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The GUI shares the same core (agent loop, tools, permissions, slash commands) and the same `~/.banana/config.json`. The interface supports Chinese and English via Settings → Appearance.
|
|
64
|
+
|
|
65
|
+
It includes session management and export (Markdown / JSON), a `/` command palette, `@` file completion, a workspace file panel, tool output details, Plan/Build switching, a task dock, three theme modes, API key and search settings, and an embedded terminal.
|
|
66
|
+
|
|
67
|
+
The look follows the same rules: warm black/white neutrals with banana yellow `#dcde8d`, hand-drawn SVG icons, and no gradients, neon, glassmorphism, or emoji.
|
|
68
|
+
|
|
69
|
+
## Platforms
|
|
70
|
+
|
|
71
|
+
| Platform | Status | Notes |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| Windows 10/11 | ✅ | PowerShell / Windows Terminal; `shell` uses `cmd.exe`, timeouts kill the process tree via `taskkill /T` |
|
|
74
|
+
| macOS 12+ | ✅ | `shell` uses `/bin/sh`; timeouts kill the process group |
|
|
75
|
+
| Linux (glibc/musl) | ✅ | Same as above; terminal uses the prebuilt `@lydell/node-pty` module |
|
|
76
|
+
| WSL | ✅ | Linux behavior when installed inside WSL (recommended for script compatibility) |
|
|
77
|
+
|
|
78
|
+
Requires **Node.js >= 20** (22 LTS or 24 recommended). `npm install -g @vincentbanana/bananacli` creates the `banana` command; the GUI package creates `banana-gui`.
|
|
79
|
+
|
|
80
|
+
Platform differences handled:
|
|
81
|
+
|
|
82
|
+
- All paths use `node:path`; the workspace sandbox validates real paths (including symlinks/junctions).
|
|
83
|
+
- `shell` uses `cmd.exe` on Windows and `/bin/sh` on Unix; interrupts and timeouts clean up child processes.
|
|
84
|
+
- Config lives in `~/.banana/` (Windows prefers `D:\BananaCLI-data` and falls back to the home directory when it is not writable).
|
|
85
|
+
- **CRLF compatible**: model-written `old_string` with `\n` matches `\r\n` files, and line endings are preserved.
|
|
86
|
+
|
|
87
|
+
## Quick start
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
# Install (package: @vincentbanana/bananacli, command: banana)
|
|
91
|
+
npm install -g @vincentbanana/bananacli
|
|
92
|
+
|
|
93
|
+
# First run enters the setup wizard (choose provider, paste key, test connection)
|
|
94
|
+
banana
|
|
95
|
+
|
|
96
|
+
# Or provide a key via environment variable
|
|
97
|
+
$env:DEEPSEEK_API_KEY = "sk-..." # PowerShell
|
|
98
|
+
export ANTHROPIC_API_KEY="sk-ant-..." # macOS / Linux
|
|
99
|
+
|
|
100
|
+
# Interactive / one-shot
|
|
101
|
+
banana
|
|
102
|
+
banana "what does src/index.ts do?"
|
|
103
|
+
banana -c # continue the last conversation
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
From source:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
git clone https://github.com/Vincentwen12/BananaGUI.git
|
|
110
|
+
cd BananaGUI
|
|
111
|
+
npm install # triggers prepare -> builds dist
|
|
112
|
+
npm start # same as node src/index.ts
|
|
113
|
+
npm test
|
|
114
|
+
npm run build
|
|
115
|
+
npm run ui:check # anti-AI UI scan
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Setup wizard
|
|
119
|
+
|
|
120
|
+
The first run (no `~/.banana/config.json` and no key detected) starts the wizard. You can rerun it with `banana --setup`:
|
|
121
|
+
|
|
122
|
+
1. **Provider**: OpenAI / Anthropic / DeepSeek / Moonshot / Qwen / Gemini / OpenRouter / Ollama, or a custom gateway, vLLM, LiteLLM.
|
|
123
|
+
2. **Connection**: confirm or edit the base URL and model.
|
|
124
|
+
3. **API key**: masked input, not written to shell history; existing env vars or saved keys can be reused.
|
|
125
|
+
4. **Permissions**: whether shell commands and file writes require confirmation (yes by default).
|
|
126
|
+
5. **Test**: sends one minimal request; failures show the upstream error and allow retrying.
|
|
127
|
+
6. Saves to `~/.banana/config.json` and enters the conversation.
|
|
128
|
+
|
|
129
|
+
> Keys are stored in plain text by default. A safer setup is to keep using environment variables (`DEEPSEEK_API_KEY`, etc.) and leave only `apiKeyEnv` in the config file.
|
|
130
|
+
|
|
131
|
+
Non-interactive setup is also supported by feeding answers to stdin:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
printf '3\nn\nsk-xxxx\nn\nn\n' | banana --setup
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## CLI
|
|
138
|
+
|
|
139
|
+
```text
|
|
140
|
+
banana interactive multi-turn conversation
|
|
141
|
+
banana "run the tests" one-shot task (no REPL)
|
|
142
|
+
|
|
143
|
+
-p, --provider <name> openai / anthropic / deepseek / moonshot / qwen / gemini / openrouter / ollama
|
|
144
|
+
-m, --model <name> override the model
|
|
145
|
+
--base-url <url> override the base URL (gateway, vLLM, LiteLLM, etc.)
|
|
146
|
+
--api-key <key> provide a key directly (not recommended; prefer env vars)
|
|
147
|
+
-s, --session <ref> load a conversation (index / id prefix / title)
|
|
148
|
+
-c, --continue continue the last conversation
|
|
149
|
+
--list list conversations and exit
|
|
150
|
+
--cwd <dir> workspace for tools
|
|
151
|
+
--allow-outside allow tools outside the workspace
|
|
152
|
+
--yolo skip all confirmations (current run only; required for non-interactive shell/write)
|
|
153
|
+
--trust-project trust this project's .banana config/plugins/AGENT.md
|
|
154
|
+
--system <text> override the system prompt
|
|
155
|
+
--no-tools no tools (plain chat)
|
|
156
|
+
--no-reasoning hide reasoning output
|
|
157
|
+
--setup run the setup wizard
|
|
158
|
+
--ui start the GUI (local server + browser)
|
|
159
|
+
--port <port> GUI port (random by default)
|
|
160
|
+
--no-open do not open a browser automatically
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
> In non-interactive mode (pipes, CI, `--one-shot`), `ask` permissions are **denied** by default. Use `--yolo` or set the relevant permission to `allow` explicitly.
|
|
164
|
+
|
|
165
|
+
## Slash commands
|
|
166
|
+
|
|
167
|
+
| Command | Description |
|
|
168
|
+
| --- | --- |
|
|
169
|
+
| `/new [title]` | New conversation (current one is saved) |
|
|
170
|
+
| `/list` | List conversations |
|
|
171
|
+
| `/use <index\|id prefix\|title>` | Switch conversation |
|
|
172
|
+
| `/rename` `/delete` `/clear` | Rename / delete / clear context |
|
|
173
|
+
| `/undo` | Revert the last turn's file changes |
|
|
174
|
+
| `/session` `/history` | Current session info / message list |
|
|
175
|
+
| `/provider [name]` `/model [name]` | Switch provider / model |
|
|
176
|
+
| `/setup` | Reconfigure provider / model / key |
|
|
177
|
+
| `/image <path\|clear>` | Attach an image (png/jpg/gif/webp) |
|
|
178
|
+
| `/tools [name\|all]` | List or enable/disable tools |
|
|
179
|
+
| `/perm <shell\|write\|network> <ask\|allow\|deny>` | Permission policy |
|
|
180
|
+
| `/compact` | Compact context manually |
|
|
181
|
+
| `/cwd [path]` | Show / change workspace |
|
|
182
|
+
| `/system [text]` | Show / replace the system prompt |
|
|
183
|
+
| `/env` | Print the environment questionnaire for `AGENT.md` |
|
|
184
|
+
| `/verify` | Run configured verification commands (default `npm test` + `npm run build`) and store results |
|
|
185
|
+
| `/phase [next\|name]` | View/switch the current phase; blocked when dependencies are unfinished |
|
|
186
|
+
| `/review` | Run an independent review agent over recent work (no file changes) |
|
|
187
|
+
| `/prefer [text\|clear]` | View/append user preferences injected into the system prompt |
|
|
188
|
+
| `/template [name]` | Show task templates: steps, acceptance, pitfalls |
|
|
189
|
+
| `/feedback <text>` | Append human feedback to `~/.banana/feedback.jsonl` |
|
|
190
|
+
| `/cls` `/exit` | Clear screen / save and exit |
|
|
191
|
+
|
|
192
|
+
Shortcuts: `Ctrl+C` interrupts the current request (twice to exit), `↑` recalls history, a trailing `\` continues input, and `@` + `Tab` completes project files.
|
|
193
|
+
|
|
194
|
+
## Plan / Build
|
|
195
|
+
|
|
196
|
+
- **Plan**: read-only tools (read, list, glob, grep, search, todo), research first, then produce a 3–7 item plan.
|
|
197
|
+
- **Build**: file writes and commands are allowed.
|
|
198
|
+
- In Plan mode `todo_write` items are always `pending`; after approval, Build starts from pending.
|
|
199
|
+
- Cancelling a plan clears the task list; switching to Build manually discards a pending plan so it cannot leak into the next turn.
|
|
200
|
+
|
|
201
|
+
## Project rules: AGENT.md
|
|
202
|
+
|
|
203
|
+
Place `AGENT.md` at the project root (or `.banana/AGENT.md`) with confirmed environment, paths, commands, and limits. The agent uses those facts directly and does not re-run `command -v` / `find` / `ls`.
|
|
204
|
+
|
|
205
|
+
```text
|
|
206
|
+
Please confirm before starting (fill only what you know; write "unknown" otherwise):
|
|
207
|
+
1 OS / shell:
|
|
208
|
+
2 Language and version:
|
|
209
|
+
3 Package manager:
|
|
210
|
+
4 Key tools (git/jq/rg/docker/…):
|
|
211
|
+
5 Project path:
|
|
212
|
+
6 Start / test / build commands:
|
|
213
|
+
7 Known limits (no sudo / proxy required / no GPU, etc.):
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Run `/env` to print this template. `AGENT.md` is runtime input only, never written into `config.json`; it is reloaded when the workspace changes. See `AGENT.md.example`.
|
|
217
|
+
|
|
218
|
+
## Memory and preferences
|
|
219
|
+
|
|
220
|
+
- `memory_write` / `memory_read` maintain two structured memory lists:
|
|
221
|
+
- Confirmed facts: content + source (user/doc/test/infer/guess) + confidence.
|
|
222
|
+
- Unknowns: item + reason + verification method.
|
|
223
|
+
- Facts and unknowns are stored with the session and injected into every later turn; switching models does not lose them.
|
|
224
|
+
- `/prefer` turns repeated corrections into user preferences injected into the next prompt.
|
|
225
|
+
|
|
226
|
+
## UI audit
|
|
227
|
+
|
|
228
|
+
- Call `ui_audit` before delivering UI, or let `write_file` / `edit_file` trigger it automatically.
|
|
229
|
+
- With `uiGuard: enforce` (default), a failed audit forces a rewrite in the same turn; after 3 attempts the turn stops and cannot claim completion.
|
|
230
|
+
- `node scripts/check-ui.mjs <file-or-dir>` scans any project.
|
|
231
|
+
- Rule IDs, bad/good examples, and the checklist live in `docs/design/`.
|
|
232
|
+
- The GUI Review panel adds a "Verify" tab: plan state, task progress, fact count, unknowns, next steps, and the latest `/verify` test/build results.
|
|
233
|
+
|
|
234
|
+
## Project trust and security
|
|
235
|
+
|
|
236
|
+
Opening an untrusted repository can expose these project-level files, so they are **not loaded by default**:
|
|
237
|
+
|
|
238
|
+
- `.banana/config.json`
|
|
239
|
+
- `.banana/tools/*.{mjs,js,ts}`
|
|
240
|
+
- `AGENT.md` / `.banana/AGENT.md`
|
|
241
|
+
|
|
242
|
+
On first encounter the agent asks for trust; after approval, a fingerprint is stored in the global config. Changing those files invalidates the fingerprint and requires trust again.
|
|
243
|
+
|
|
244
|
+
- CLI: interactive sessions ask; non-interactive sessions skip with a hint. Use `--trust-project` to trust explicitly.
|
|
245
|
+
- GUI: shows a "Trust and load" dialog on startup.
|
|
246
|
+
- Even when trusted, project config only applies whitelisted keys: `maxSteps`, `maxContextChars`, `showReasoning`, `disabledPlugins`, and non-secret `search` fields.
|
|
247
|
+
- `providers`, `permissions`, `allowOutsideWorkspace`, `systemPrompt`, and `sessionDir` always come from global config.
|
|
248
|
+
- Plugin approval defaults to `shell` (which defaults to `ask`); project plugins load only after trust.
|
|
249
|
+
|
|
250
|
+
Other safety defaults:
|
|
251
|
+
|
|
252
|
+
- API keys live in `~/.banana/config.json`; do not commit them. `.banana/` is ignored by `.gitignore`.
|
|
253
|
+
- Non-interactive `ask` permissions are denied by default; `--yolo` must be explicit.
|
|
254
|
+
- Workspace paths are validated by real path; symlinks cannot escape the workspace.
|
|
255
|
+
|
|
256
|
+
## Diff preview and undo
|
|
257
|
+
|
|
258
|
+
- Before a file write/edit that needs confirmation, the exact added/removed lines are shown (up to 40 lines).
|
|
259
|
+
- Before each tool write, the previous content is snapshotted to `~/.banana/backups/<sessionId>/` (up to 30 turns).
|
|
260
|
+
- `/undo` restores modified files and deletes newly created ones from the last turn.
|
|
261
|
+
- Files over 4 MB are not backed up; `/undo` lists them as "not backed up" instead of deleting them.
|
|
262
|
+
- Conversation history is not rolled back; `shell` and plugin side effects cannot be undone.
|
|
263
|
+
|
|
264
|
+
## Images
|
|
265
|
+
|
|
266
|
+
```text
|
|
267
|
+
/image screenshot.png
|
|
268
|
+
look at this error
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Images are encoded as data URLs and sent with the next message. Both OpenAI-compatible and Anthropic protocols are supported; the limit is 4 MB per image (png / jpg / gif / webp). `/image` without arguments lists pending images; `/image clear` clears them.
|
|
272
|
+
|
|
273
|
+
## Plugins
|
|
274
|
+
|
|
275
|
+
Put a `.mjs` (`.js` / `.ts` also supported) in `~/.banana/tools/` (global) or `<project>/.banana/tools/` (project, requires trust) with a default export:
|
|
276
|
+
|
|
277
|
+
```js
|
|
278
|
+
// ~/.banana/tools/http_status.mjs
|
|
279
|
+
export default {
|
|
280
|
+
name: 'http_status',
|
|
281
|
+
description: 'Check the HTTP status of a URL',
|
|
282
|
+
parameters: {
|
|
283
|
+
type: 'object',
|
|
284
|
+
properties: { url: { type: 'string', description: 'Target URL' } },
|
|
285
|
+
required: ['url'],
|
|
286
|
+
additionalProperties: false,
|
|
287
|
+
},
|
|
288
|
+
approval: 'network', // never | write | shell | network; default is shell
|
|
289
|
+
async run(input) {
|
|
290
|
+
const response = await fetch(String(input.url), { method: 'HEAD' });
|
|
291
|
+
return { ok: response.ok, content: `${input.url} -> ${response.status}` };
|
|
292
|
+
},
|
|
293
|
+
};
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Name conflicts, a missing `run`, or invalid fields are reported and skipped. Plugins run with the current Node process privileges, exactly like your own code: only use trusted scripts.
|
|
297
|
+
|
|
298
|
+
## Web search
|
|
299
|
+
|
|
300
|
+
- Default `auto`: use Tavily / Brave when a key is available, otherwise merge Bing / DuckDuckGo free sources.
|
|
301
|
+
- Keys can also be set in GUI Settings → Web search; they are never returned by `/api/info`.
|
|
302
|
+
- `depth=deep` or the "Deep search" toggle reads the first few pages; off by default.
|
|
303
|
+
- Search language defaults to English/technical sources; `auto` and `zh` are available.
|
|
304
|
+
|
|
305
|
+
## Cost estimation and budget
|
|
306
|
+
|
|
307
|
+
Per-turn and per-session cost is estimated from the built-in price table (USD per million tokens); unknown models show nothing. Override prices per provider:
|
|
308
|
+
|
|
309
|
+
```json
|
|
310
|
+
{ "pricing": { "input": 0.27, "output": 1.1 } }
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
Set a per-turn budget in the global config; the turn stops before the next model call when exceeded:
|
|
314
|
+
|
|
315
|
+
```json
|
|
316
|
+
{ "budget": { "tokens": 200000, "minutes": 30 } }
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
## Trace
|
|
320
|
+
|
|
321
|
+
Every turn writes `~/.banana/traces/<sessionId>-<turnId>.jsonl` with tool calls, timings, retries, compaction, and the stop reason for later replay.
|
|
322
|
+
|
|
323
|
+
## Evaluation and failure library
|
|
324
|
+
|
|
325
|
+
```bash
|
|
326
|
+
npm run eval # contract eval: prompt sections, knowledge pack, UI scan, multiline, grep, plan fields
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Real failures are recorded in `docs/failures.md` with scene, root cause, fix, and the test that covers it.
|
|
330
|
+
|
|
331
|
+
## Configuration
|
|
332
|
+
|
|
333
|
+
Global `~/.banana/config.json`; project `<workspace>/.banana/config.json` requires explicit trust and applies only whitelisted keys.
|
|
334
|
+
|
|
335
|
+
```json
|
|
336
|
+
{
|
|
337
|
+
"current": "deepseek",
|
|
338
|
+
"providers": {
|
|
339
|
+
"deepseek": {
|
|
340
|
+
"protocol": "openai",
|
|
341
|
+
"baseUrl": "https://api.deepseek.com/v1",
|
|
342
|
+
"model": "deepseek-chat",
|
|
343
|
+
"apiKeyEnv": "DEEPSEEK_API_KEY"
|
|
344
|
+
},
|
|
345
|
+
"my-gateway": {
|
|
346
|
+
"protocol": "openai",
|
|
347
|
+
"baseUrl": "https://llm.internal/v1",
|
|
348
|
+
"model": "qwen2.5-coder",
|
|
349
|
+
"apiKeyEnv": "INTERNAL_KEY",
|
|
350
|
+
"pricing": { "input": 0.4, "output": 1.2 }
|
|
351
|
+
}
|
|
352
|
+
},
|
|
353
|
+
"permissions": { "shell": "ask", "write": "ask", "network": "allow" },
|
|
354
|
+
"maxSteps": 40,
|
|
355
|
+
"maxContextChars": 160000,
|
|
356
|
+
"allowOutsideWorkspace": false,
|
|
357
|
+
"showReasoning": true,
|
|
358
|
+
"trustedProjects": {},
|
|
359
|
+
"budget": { "tokens": 200000, "minutes": 30 },
|
|
360
|
+
"verifyCommands": ["npm test", "npm run build"],
|
|
361
|
+
"uiGuard": "enforce"
|
|
362
|
+
}
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
Anthropic adds `cache_control: ephemeral` to `system` and tool definitions (prompt caching). Set `"promptCaching": false` for gateways that reject it.
|
|
366
|
+
|
|
367
|
+
Environment variables: `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` / `MOONSHOT_API_KEY` / `DASHSCOPE_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY`; optional search keys `TAVILY_API_KEY` / `BRAVE_API_KEY`; overrides `BANANA_PROVIDER` / `BANANA_MODEL` / `BANANA_BASE_URL` / `BANANA_SHOW_REASONING` / `BANANA_HOME` / `BANANA_CONFIG`.
|
|
368
|
+
|
|
369
|
+
`protocol` is either `openai` (OpenAI-compatible) or `anthropic` (native Claude).
|
|
370
|
+
|
|
371
|
+
## Repository layout
|
|
372
|
+
|
|
373
|
+
```text
|
|
374
|
+
src/ CLI core
|
|
375
|
+
index.ts entry: argument parsing, wiring, project trust prompt
|
|
376
|
+
config/
|
|
377
|
+
config.ts config load/merge, env overrides, system prompt, AGENT.md
|
|
378
|
+
project-trust.ts project artifact fingerprint and trust checks
|
|
379
|
+
providers/ OpenAI / Anthropic protocols, SSE, pricing
|
|
380
|
+
agent/ agent loop and context compaction
|
|
381
|
+
tools/ file / shell / web / todo / plugin tools
|
|
382
|
+
server/ local GUI server and terminal PTY
|
|
383
|
+
session/ session storage, backups, /undo
|
|
384
|
+
cli/ REPL, slash commands, completion, setup wizard, terminal UI
|
|
385
|
+
ui/ browser UI (HTML/CSS/JS, no frontend framework)
|
|
386
|
+
gui/ standalone GUI package (launchers, Electron shell, synced ui/)
|
|
387
|
+
docs/design/ UI principles, tokens, components, states, accessibility, checklist, reference cards
|
|
388
|
+
docs/failures.md failure library
|
|
389
|
+
docs/prompt-versions.md prompt and knowledge-pack version log
|
|
390
|
+
scripts/ build, sync, UI scan, release
|
|
391
|
+
test/ mock provider and full test suite
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
## Development
|
|
395
|
+
|
|
396
|
+
```bash
|
|
397
|
+
npm run typecheck # tsc --noEmit
|
|
398
|
+
npm test # typecheck + UI scan + full tests
|
|
399
|
+
npm run dev # node --watch
|
|
400
|
+
npm run build # compile to dist/ (for publishing)
|
|
401
|
+
npm run ui:check # anti-AI UI scan only
|
|
402
|
+
npm run eval # contract eval (prompt/knowledge pack/key behavior)
|
|
403
|
+
npm run ab # contract A/B for two prompt suffixes
|
|
404
|
+
npm run gui:sync # src/ui -> gui/ui
|
|
405
|
+
npm run gui:check # verify both UI copies match
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
Comment convention:
|
|
409
|
+
|
|
410
|
+
- Code comments use Chinese prose.
|
|
411
|
+
- APIs, protocols, commands, paths, and proper nouns stay in English, e.g. `OpenAI`, `SSE`, `scanner-allow`.
|
|
412
|
+
- `// scanner-allow: terminal-palette` and `// scanner-allow-end` are UI scanner markers and must stay in English.
|
|
413
|
+
- Run `npm run ui:check` before shipping UI changes and read `docs/design/checklist.md`.
|
|
414
|
+
|
|
415
|
+
## Known limits
|
|
416
|
+
|
|
417
|
+
- Built-in provider base URLs and model names may need adjusting for some services via `/model` or config.
|
|
418
|
+
- Context compaction estimates tokens from character counts; lower `maxContextChars` for very long sessions.
|
|
419
|
+
- Without Tavily/Brave keys, `web_search` merges Bing / DuckDuckGo and reports an explicit error if both fail.
|
|
420
|
+
- Images are stored as data URLs in the session JSON; many large images make the file large (4 MB per image limit).
|
|
421
|
+
- `/undo` only covers `write_file` / `edit_file`; `shell` and plugin side effects cannot be rolled back.
|
|
422
|
+
- Plugins run with current process privileges; only use trusted scripts, and project plugins require explicit trust.
|
|
423
|
+
|
|
424
|
+
## License
|
|
425
|
+
|
|
426
|
+
MIT. See [LICENSE](LICENSE).
|