@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.
Files changed (84) hide show
  1. package/README.en.md +426 -0
  2. package/README.md +229 -133
  3. package/design-tokens.json +33 -0
  4. package/dist/agent/context.js +8 -3
  5. package/dist/agent/loop.js +71 -1
  6. package/dist/agent/retrieval.js +59 -0
  7. package/dist/agent/review.js +29 -0
  8. package/dist/cli/commands.js +211 -2
  9. package/dist/cli/continuation.js +14 -0
  10. package/dist/cli/repl.js +49 -16
  11. package/dist/cli/templates.js +23 -0
  12. package/dist/config/config.js +161 -21
  13. package/dist/config/project-trust.js +52 -0
  14. package/dist/config/version.js +3 -0
  15. package/dist/index.js +36 -5
  16. package/dist/providers/reasoning.js +7 -8
  17. package/dist/server/ui-server.js +228 -30
  18. package/dist/session/backups.js +17 -4
  19. package/dist/session/phases.js +51 -0
  20. package/dist/session/store.js +49 -10
  21. package/dist/session/trace.js +31 -0
  22. package/dist/session/verify.js +60 -0
  23. package/dist/tools/fs.js +34 -10
  24. package/dist/tools/index.js +11 -1
  25. package/dist/tools/memory.js +121 -0
  26. package/dist/tools/plugins.js +3 -2
  27. package/dist/tools/todo.js +25 -1
  28. package/dist/tools/ui.js +41 -0
  29. package/dist/ui/app.js +558 -67
  30. package/dist/ui/index.html +5 -1
  31. package/dist/ui/style.css +237 -240
  32. package/dist/util/ui-audit.js +192 -0
  33. package/docs/ab-testing.md +26 -0
  34. package/docs/assets/README.md +30 -0
  35. package/docs/assets/build-real-en.png +0 -0
  36. package/docs/assets/build-real.png +0 -0
  37. package/docs/assets/changes-real-en.png +0 -0
  38. package/docs/assets/changes-real.png +0 -0
  39. package/docs/assets/cli.png +0 -0
  40. package/docs/assets/cli.svg +29 -0
  41. package/docs/assets/demo-en.gif +0 -0
  42. package/docs/assets/demo-zh.gif +0 -0
  43. package/docs/assets/demo.png +0 -0
  44. package/docs/assets/demo.svg +59 -0
  45. package/docs/assets/gui-real-en.png +0 -0
  46. package/docs/assets/gui-real.png +0 -0
  47. package/docs/assets/gui.png +0 -0
  48. package/docs/assets/gui.svg +61 -0
  49. package/docs/assets/review-real-en.png +0 -0
  50. package/docs/assets/review-real.png +0 -0
  51. package/docs/assets/review.png +0 -0
  52. package/docs/assets/review.svg +39 -0
  53. package/docs/assets/social-preview.png +0 -0
  54. package/docs/assets/social-preview.svg +35 -0
  55. package/docs/design/README.md +43 -0
  56. package/docs/design/accessibility.md +32 -0
  57. package/docs/design/checklist.md +25 -0
  58. package/docs/design/components.md +41 -0
  59. package/docs/design/content.md +31 -0
  60. package/docs/design/data-display.md +33 -0
  61. package/docs/design/examples/README.md +35 -0
  62. package/docs/design/examples/bad/big-radius.css +4 -0
  63. package/docs/design/examples/bad/emoji.tsx +3 -0
  64. package/docs/design/examples/bad/glass.css +5 -0
  65. package/docs/design/examples/bad/gradient-hero.css +11 -0
  66. package/docs/design/examples/bad/heavy-shadow.css +3 -0
  67. package/docs/design/examples/bad/neon.css +8 -0
  68. package/docs/design/examples/good/pricing-page.css +74 -0
  69. package/docs/design/examples/good/pricing-page.html +31 -0
  70. package/docs/design/forms.md +32 -0
  71. package/docs/design/layout.md +32 -0
  72. package/docs/design/motion.md +33 -0
  73. package/docs/design/principles.md +33 -0
  74. package/docs/design/refs/github-primer.md +4 -0
  75. package/docs/design/refs/govuk.md +4 -0
  76. package/docs/design/refs/linear.md +4 -0
  77. package/docs/design/refs/notion.md +4 -0
  78. package/docs/design/refs/stripe.md +4 -0
  79. package/docs/design/states.md +34 -0
  80. package/docs/design/tokens.md +39 -0
  81. package/docs/design/typography-spacing.md +37 -0
  82. package/docs/failures.md +75 -0
  83. package/docs/prompt-versions.md +10 -0
  84. package/package.json +9 -4
package/README.en.md ADDED
@@ -0,0 +1,426 @@
1
+ # BananaCLI + BananaGUI
2
+
3
+ English | [中文](README.md)
4
+
5
+ ![AI-generated](https://img.shields.io/badge/code-AI--generated-dcde8d?style=flat-square)
6
+ ![human reviewed](https://img.shields.io/badge/review-human--reviewed-2f7d50?style=flat-square)
7
+ ![tests](https://img.shields.io/badge/tests-passing-2f7d50?style=flat-square)
8
+ ![license](https://img.shields.io/badge/license-MIT-161616?style=flat-square)
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
+ [![Real GUI demo (about 14 seconds)](https://cdn.jsdelivr.net/gh/Vincentwen12/BananaGUI@main/docs/assets/demo-en.gif)](https://github.com/Vincentwen12/BananaGUI/blob/main/docs/assets/demo-en.gif)
23
+
24
+ ![Banana GUI](docs/assets/gui-real-en.png)
25
+
26
+ ![Review verify tab](docs/assets/review-real-en.png)
27
+
28
+ | CLI |
29
+ |---|
30
+ | ![CLI](docs/assets/cli.png) |
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).