lowe 0.1.0__py3-none-any.whl

lowe-0.1.0.dist-info/METADATA

@@ -0,0 +1,683 @@
+Metadata-Version: 2.4
+Name: lowe
+Version: 0.1.0
+Summary: LOWE: an AI assistant and terminal coding agent built for developers in China
+Author-email: Lowe Tekam <lowetekam@gmail.com>
+License: Proprietary
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Requires-Dist: prompt_toolkit>=3.0.43
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pathspec>=0.12
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: tree-sitter-java>=0.23
+Requires-Dist: tree-sitter-go>=0.23
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: pypdf>=5.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: python-docx>=1.1
+Requires-Dist: python-pptx>=1.0
+Requires-Dist: reportlab>=4.0
+Requires-Dist: segno>=1.6
+Provides-Extra: voice
+Requires-Dist: faster-whisper>=1.1; extra == "voice"
+Requires-Dist: av<16,>=14; extra == "voice"
+Provides-Extra: wake
+Requires-Dist: sounddevice>=0.4; extra == "wake"
+Provides-Extra: phone
+Requires-Dist: cryptography>=42; extra == "phone"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-jsonschema; extra == "dev"
+Requires-Dist: playwright>=1.40; extra == "dev"
+Requires-Dist: pywinpty>=2.0; sys_platform == "win32" and extra == "dev"
+Requires-Dist: pyte>=0.8; extra == "dev"
+
+# LOWE
+
+[中文版 README](README.zh-CN.md)
+
+LOWE is an AI assistant and terminal coding agent built for developers in China.
+It runs on Chinese model providers (DeepSeek first, then GLM, Kimi and Qwen) and keeps
+all data on your machine.
+
+- **LOWE Code** (`lowe`): a coding agent in your terminal. It has file and shell tools,
+  checks its own work (tests, build, review), and has permission modes, a Docker
+  sandbox, memory, sessions and budgets. It also has helper agents, git, GitHub/Gitee,
+  hooks, MCP tools and remote projects over SSH (`--remote`), and it learns from its
+  own work.
+- **LOWE chat** (`lowe web`): a chat app in the browser. It has files, a side panel for
+  code and web pages, projects, and personal links for a team. It also comes as a
+  Docker image for a server.
+- **The VS Code extension**: LOWE Code in a panel, with each change shown as a diff
+  beside the code.
+
+How it compares with Claude Code, with numbers: [COMPARISON.md](COMPARISON.md). What
+comes next: [ROADMAP.md](ROADMAP.md).
+
+## Install
+
+See **[INSTALL.md](INSTALL.md)** (Windows, WSL, Linux and macOS, with Chinese mirrors).
+In short:
+
+```bash
+python -m pip install --user pipx && python -m pipx ensurepath   # then open a new terminal
+pipx install lowe-0.1.0-py3-none-any.whl     # or: pipx install <LOWE's source folder>
+setx DEEPSEEK_API_KEY "sk-..."               # Windows; Linux/macOS: export it in ~/.bashrc
+```
+
+Keys for other providers are optional. With them LOWE can continue a task elsewhere when
+DeepSeek fails (see [LOWE models](#lowe-models)): `ZHIPUAI_API_KEY` (GLM),
+`MOONSHOT_API_KEY` (Kimi), `DASHSCOPE_API_KEY` (Qwen).
+
+## Use
+
+```bash
+lowe                                   # interactive; Ctrl+C stops a task, Ctrl+D quits
+lowe -p "fix the failing test"         # one task, then exit
+lowe --model steady                    # another LOWE model (see below)
+lowe --bugfix -p "users say X is wrong"  # reproduce with a failing test first, then fix
+lowe --sandbox                         # run every shell command in a Docker container
+```
+
+After LOWE changes files it runs diagnostics, the project's tests and build, sends any
+failures back to the model, has a reviewer read the diff, and then reports what passed,
+what failed and what it could not verify. The commands it runs are kept in `LOWE.md`
+in your project; edit that file to change them. Turn parts off with `--no-verify`,
+`--no-review`, `--no-build`.
+
+## Hands-free: say "LOWE" (`lowe voice`)
+
+```bash
+pip install "lowe[voice,wake]"        # Whisper on this computer, and the microphone
+lowe voice                            # listen for the wake word, hands free
+lowe voice --lang en --model base     # faster: your language, a smaller model
+lowe voice --wav me.wav --dry-run     # read a recording: what did it hear?
+```
+
+Say the name and the request in one breath:
+
+- **"LOWE code, fix the failing test"** wakes LOWE and runs the task in this folder (LOWE
+  Code, with the project's own settings, permissions and budget).
+- **"LOWE web, show today's chats"** opens LOWE web: the window that is already serving, or
+  a new one.
+- **"LOWE"** alone: a chime, then the next phrase is the request.
+- 洛威 works too, and a Chinese request may follow the English name.
+
+In the browser, the ear button next to the microphone does the same (`/api/wake`). The page
+watches the microphone's loudness itself and only sends a phrase when somebody spoke, so an
+always-on listener costs no model calls, and nothing leaves this computer: the same local
+Whisper the microphone uses reads the words.
+
+Two things are on purpose. It is more forgiving than Siri about the name ("Loewe", "lowe's",
+"loww", "洛威" all wake it, accents included) and stricter than Siri about everything else
+("below", "lower", "yellow", "law of gravity" never do). And the request is read from the
+same breath as the name, so there is no waiting turn after the chime. The rules are in
+`lowe_core/wake.py`, the tests in `tests/test_wake.py`; `--min-confidence 0.9` takes only
+the real spellings of the name, for a loud room.
+
+## Use LOWE from Python (the SDK)
+
+```bash
+pip install "lowe[voice]"           # only needed for the microphone; the SDK needs nothing extra
+python -c "from lowe_core.sdk import Lowe; print(Lowe)"
+```
+
+```python
+import asyncio
+from lowe_core.agent import AgentText
+from lowe_core.sdk import Lowe
+
+async def main() -> None:
+    lowe = Lowe(root=".", mode="accept-edits")
+    async for event in lowe.stream("fix the failing test in tests/test_parse.py"):
+        if isinstance(event, AgentText):
+            print(event.text, end="")
+    result = await lowe.ask("add a test for the empty case")
+    print(result.text, result.reason, result.cny, result.changes)
+
+asyncio.run(main())
+```
+
+It is the same loop, tools, permission policy and budget the terminal runs, with a result a
+program can read (`text`, `reason`, `steps`, `cny`, `changes`). A library has nobody to answer
+a permission question, so anything the policy cannot decide is refused unless you pass
+`approver=`. Sessions, verification and the reviewer pass stay in the CLI: for CI, use
+`lowe -p "..." --output-format json`. Full reference: [docs/SDK.md](docs/SDK.md).
+
+## A message when a long task is done (WeCom, DingTalk, Feishu)
+
+```bash
+lowe notify show                              # what is configured, and after how long
+lowe notify test                              # send a test message now
+lowe notify test --url https://open.feishu.cn/open-apis/bot/v2/hook/...   # try one
+```
+
+One URL in `~/.lowe/settings.json`, and a task that runs past two minutes tells your phone:
+
+```json
+{"notify": {"url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...",
+            "minSeconds": 120}}
+```
+
+The service is read from the URL — `qyapi.weixin.qq.com` is WeCom (企业微信),
+`oapi.dingtalk.com` is DingTalk (钉钉; add `"secret": "SEC..."` if that robot uses 加签),
+`open.feishu.cn` / `open.larksuite.com` is Feishu (飞书) — or name it with `"kind"`. Any other
+URL is sent `{"text": ...}`.
+
+The message is metadata only: the task as you typed it (300 characters), how it ended, the
+time, the cost and the folder — no file contents and no model output. Only **your own**
+settings can set it: a repository's shared `.lowe/settings.json` is ignored (kept aside as
+untrusted), because a webhook carries a task's text off this machine. `"notify": false` or
+`LOWE_NOTIFY=0` turns it off in one place.
+
+## What will this cost? (`lowe forecast`)
+
+```bash
+lowe forecast "fix the failing tests"     # ≈ ¥0.04, about 3 min — from 14 similar tasks (tests)
+lowe forecast --json "add a dark mode"    # the same numbers for a script
+lowe -p "fix the failing tests"           # prints the same line, then runs
+```
+
+The numbers come from your own `~/.lowe/outcomes.jsonl`, which every finished task already
+writes: the **median** money and time of the recent tasks of the same kind (bugfix, tests,
+feature, refactor, build, question, other), preferring the model you are about to run. The
+median, not the average, so one runaway refactor does not inflate every later forecast.
+
+It stays **silent until five such tasks exist** — a forecast made of two data points is a guess
+wearing a number. Durations were only recorded from this version on, so older history still
+forecasts the money and simply leaves the time out.
+
+## Batch work at the cheaper hours (`--at-off-peak`)
+
+DeepSeek charges **twice as much** on weekday mornings and afternoons (Beijing 09:00–12:00
+and 14:00–18:00) as it does at night and at weekends. A long job that nobody is waiting for
+can run in the cheap window instead:
+
+```bash
+lowe --at-off-peak -p "run the whole test suite and fix what fails"   # queued if it is peak
+lowe queue                    # what is waiting, and when it opens
+lowe queue --run              # run the jobs whose window is open now
+lowe queue --wait             # sit here until the window opens, then run
+lowe queue --run-all          # the escape hatch: run everything now
+lowe queue --clear
+```
+
+Queuing only happens during a peak hour; off-peak the task runs immediately as usual. The
+queue is `~/.lowe/queue.json`, and a queued job runs as an ordinary `lowe -p` task in its own
+folder, so the usual permissions, budget and verification apply. A job that fails stays
+queued with one more try recorded; nothing runs unless you ask (`--run`, `--wait`). Providers
+without a peak schedule (Kimi, Qwen, a local model) never wait.
+
+## LOWE chat in the browser (`lowe web`)
+
+```bash
+lowe web                    # starts the chat app and opens it in your browser
+lowe web --no-browser --port 9000
+lowe web --new-link         # a new secret link; old links stop working
+```
+
+`lowe web` prints a link with a secret in it; opening it lets that browser in (keep the
+link private). Chats, projects and files are stored in `~/.lowe/web/lowe.db` on your
+machine.
+
+- Streamed answers with Markdown and coloured code, copy buttons, Stop, Regenerate and
+  Edit; light and dark mode; Chinese and English (the 中文 / English button).
+- The LOWE model menu (the same models, prices and fallback as LOWE Code) and a **Think**
+  switch for hard questions (slower and dearer).
+- **Files**: attach code, text (UTF-8 or GBK) and PDF files (with a text layer; scanned
+  PDFs have no text to read). Up to 20 MB each.
+- **Side panel**: long code and whole web pages open next to the chat; web pages run as a
+  live **Preview** in a locked-down frame.
+- **Projects**: instructions and files shared by every chat in the project.
+- **No surprise costs.**
+  - The meter next to Send shows what the message you are typing will probably cost
+    and what you spent today (`≈ ¥0.004 · today ¥0.12 of ¥5.00`).
+  - Click it to set a **daily cap**: once it is reached, LOWE starts no new answer.
+    It never cuts one off half way.
+  - Click it also to set the amount above which LOWE **asks before sending** (¥0.05 by
+    default): useful for a big PDF.
+  - An answer that stopped half way is charged what the provider really billed for it,
+    estimated (`≈ ¥`). A request that failed before answering costs nothing.
+  - Each person with a link has their own cap and meter.
+- **Open in LOWE Code**: saves the chat as a LOWE Code session in a project folder you
+  choose and opens a terminal (`lowe --cwd <folder> --resume <id>`), so the agent can carry
+  on with tools.
+- Your notes (`~/.lowe/LOWE.md`), your own lessons and LOWE's know-how apply here too.
+
+### Several people (personal links)
+
+Whoever runs `lowe web` is its owner. Give other people their own link:
+
+```bash
+lowe web add-user alice        # prints Alice's personal link (shown once)
+lowe web users                 # everyone with a link, their chats and what they cost
+lowe web reset-link alice      # a new link for Alice; the old one stops working
+lowe web remove-user alice     # Alice's link stops working (add --delete-chats to delete them)
+```
+
+Each person sees only their own projects, chats and files, and only a hash of each link
+is stored. Your own notes and lessons stay out of other people's chats, and only the
+owner can hand a chat to LOWE Code, because handing over writes to the server's disk.
+Everyone uses the server's API keys.
+
+### On a server
+
+`lowe web --host 0.0.0.0` lets other computers in with a link. For a team, use the
+Docker image (`docker build -t lowe-web .`, see [INSTALL.md](INSTALL.md#lowe-chat-on-a-server-docker)).
+It runs as an ordinary user and keeps everything in the `/data` volume. Put HTTPS in
+front of it (a reverse proxy) and set `--public-url https://lowe.example.com` or
+`LOWE_PUBLIC_URL`, so the printed links use that address and the login cookie is sent
+over HTTPS only.
+
+## LOWE models
+
+`/model` lists LOWE's models with what they run on, measured with LOWE's own eval suite
+([evals/RANKING.md](evals/RANKING.md)):
+
+| LOWE model | Runs on | Tasks passed | ¥ per task |
+|---|---|---|---|
+| **Swift** (default) | DeepSeek Flash | 98% | ¥0.024 |
+| Steady | GLM-5.3 Flash | 94% | ¥0.033 |
+| Focus | Kimi K2.7 Code | 100%* | ¥0.19 |
+| Wide | Qwen3 Coder Flash | 89%* | ¥0.60 |
+| Deep (only when chosen) | DeepSeek V4 Pro | 93% | ¥0.091 |
+
+\* measured on 9-11 tasks only. Switch with `/model steady` or `lowe --model steady`; a
+provider's own model names (`/model glm-4.7-flash`) work too.
+
+- **Fallback.** When a provider fails in a way another can get past (no balance, a bad
+  key, an outage, a rate limit LOWE could not wait out), LOWE says so and continues the
+  same task on the next model in the table that has a key: Swift → Steady → Focus → Wide.
+  Change the order with `"fallback": ["steady", "wide"]` in settings; turn it off with
+  `"fallback": false` or `--no-fallback`.
+- **Deep is never used on its own.** It passed fewer tasks than Swift at 3.7x the price,
+  so neither fallback nor `--router`/`--team` choose it; only `/model deep`,
+  `--model deep` or `--strong-model deep` do.
+- **Budget.** A task stops once it has cost ¥1 unless you set another limit (below).
+
+## Memory, sessions and cost
+
+- `LOWE.md` in your project holds notes LOWE reads at the start of every session
+  (structure, commands, conventions). Type `/init` and LOWE writes it for you.
+  `~/.lowe/LOWE.md` holds your own preferences for all projects.
+- Every conversation is saved in `~/.lowe/sessions/` (secrets removed). Continue one with
+  `lowe --resume` (choose from a list), `lowe --resume <id>`, or `/resume` inside LOWE.
+- Long conversations are summarised automatically when they pass the model's context
+  budget. The start of the prompt never changes, so DeepSeek's prompt cache keeps working
+  (cached input costs about 1/50 of uncached input).
+- `/cost` shows tokens and cost in ¥ and $ for the session and the last task, and the
+  cache hit rate. Each task stops at ¥1 by default; change it with `--budget-cny 0.5` or
+  `--budget-tokens 200000`, or in settings: `"budget": {"cny": 0.5}`. `0` means no limit.
+
+| Command | |
+|---|---|
+| `/help` | all commands |
+| `/cost` | tokens, ¥ and $, cache hit rate |
+| `/model [name]` | LOWE models with measured pass rates; switch with `/model steady` |
+| `/provider [id]` | show or switch the provider |
+| `/permissions` | show the mode and rules; `/permissions mode auto`, `/permissions allow bash:npm run *` |
+| `/plan` / `/plan off` | plan mode on or off |
+| `/review` | review your uncommitted git changes for bugs |
+| `/learn` | lessons LOWE remembers: `/learn add <text>`, `/learn edit <n> <text>`, `/learn rm <n>` |
+| `/skills` | recipes LOWE wrote after verified multi-step tasks: `/skills show <n>`, `/skills rm <n>` |
+| `/mcp` | MCP servers and their tools |
+| `/stats` | your results per kind of task and LOWE model; `/stats clear` deletes them |
+| `/init` | write LOWE.md for this project |
+| `/resume` | continue an earlier conversation |
+| `/show [n]` | show a long tool output in full |
+| `/lang zh` / `/lang en` | interface language (default: your system language; or `--lang`) |
+| `/clear` | start a new conversation |
+| `/exit` | quit (or Ctrl+D) |
+
+After each task a status line shows the model, the session's cost, how full the context
+is, the permission mode and the git branch with its number of changed files.
+
+## LOWE learns
+
+After a task that ran into a problem and still finished (a failed command or tool call,
+tests that failed before they passed), LOWE asks its cheapest model whether there is
+anything worth remembering for later tasks in this project, and shows what it keeps:
+
+```
+✎ Learned for next time: This project has no `npm test` script; run `npm run check`.
+```
+
+Lessons live in `<project>/.lowe/lessons.md` (yours for all projects:
+`~/.lowe/lessons.md`), plain Markdown you can read and edit. `/learn` lists them,
+`/learn edit <n> <text>` changes one, `/learn rm <n>` deletes it. They apply from the next
+conversation. A lesson never contains links, download-and-run commands, secrets or
+anything about permissions, and lessons cannot change what LOWE is allowed to do. Tasks
+without problems cost nothing extra; a lesson costs about ¥0.001.
+
+**Skills.** After a multi-step task whose changes passed verification, LOWE asks whether
+it was a procedure likely to come up again (a new endpoint, a migration, a new page) and
+if so writes a recipe to `<project>/.lowe/skills/<name>.md`. When a later task matches a
+skill, LOWE says so and hands the recipe to the model with the task. A skill counts its
+successes and failures, and one that fails more often than it works is deleted. `/skills`
+lists them, `/skills show <n>` and `/skills rm <n>` show or delete one. Matching is local
+(word overlap, Chinese included): nothing is downloaded or sent anywhere.
+
+Turn lessons and skills off with `--no-learn` or `"autoLearn": false`.
+
+**Built-in know-how.** LOWE ships with short expert recipes for common work in China:
+- package mirrors (pip, npm, Maven, Gradle, Go, conda, Cargo, Hugging Face, Docker);
+- WeChat mini programs, uni-app, Spring Boot, Vue 3, Python and Go projects;
+- Chinese text and encodings, payments and secrets (WeChat Pay, Alipay);
+- Windows pitfalls, a bug-fixing method, writing tests, git in teams, and working cheaply.
+
+A task that mentions a topic's keywords gets that recipe with it (`📚 LOWE know-how: ...`);
+most tasks get none and cost nothing extra. They are in `lowe_core/knowledge/`, and
+`"knowHow": false` turns them off.
+
+**Which model works best for you.** LOWE records every task's outcome in
+`~/.lowe/outcomes.jsonl`: the kind of task (bug fix, feature, refactor, tests, build,
+question; English and Chinese), the LOWE model, whether it was solved (finished, and
+verified if files changed) and its cost. Never the task's text or code. `/stats` shows
+it; `/stats clear` deletes it. With `--auto-model` (or `"autoModel": true`), LOWE picks
+the model with the best value (tasks solved per yuan) for each kind of task, learning from
+your own results. It starts from the eval suite's numbers and keeps trying the others now
+and then (Thompson sampling). It chooses between Swift and Steady unless you list others,
+e.g. `"autoModel": ["swift", "steady", "focus"]`.
+
+`/stats` also shows the last four weeks: cost, tokens and prompt-cache hits per task, and
+the change in ¥ per task from the week before.
+
+**Training data (opt-in).** With `"collectTraining": true`, each solved task is saved,
+anonymised (secrets removed; project folder, home folder and your git name and e-mail
+replaced), to `~/.lowe/dataset/`. Only tasks on providers whose terms allow training on
+their output are kept (DeepSeek, local models). `scripts/finetune_lora.py` fine-tunes an
+open coding model on it later: see [docs/TRAINING.md](docs/TRAINING.md).
+
+**Code index.** The `search_code` tool finds code by what it does ("where refunds are
+calculated", "用户登录校验") from a local word index of the project: one entry per
+function, class or 50-line region. The index is kept in `~/.lowe/index/` and only changed
+files are read again (LOWE's own repository: about 500 files, 0.9 s the first time,
+0.2 s after, 200 KB). It runs on your machine and needs no download.
+
+## Helpers, plans, git, GitHub and Gitee
+
+- For bigger tasks LOWE keeps a checklist (☐ ▶ ☑) and updates it as it works.
+- LOWE can hand a wide search to a **helper** on the cheapest model of the provider. The
+  helper can only read; its exploration stays out of the main conversation, and its cost is
+  added to yours. Turn helpers off with `--no-helpers`.
+- LOWE commits only when you ask, after looking at `git status` and `git diff`.
+- `forge` reads issues and opens pull requests on the project's GitHub or Gitee repository
+  (from `git remote origin`). Tokens: `GITHUB_TOKEN`/`GH_TOKEN`, `gh auth token` or git's
+  saved credentials for GitHub; `GITEE_TOKEN` for Gitee. Opening a pull request is always
+  confirmed first, in every mode.
+
+## Router, team and best-of-N
+
+Ways to spend more on a strong model where it matters. The strong model is the one you
+name with `--strong-model` (a LOWE model of the same provider, e.g. `deep`, or a model
+name; or `"strongModel"` in settings). Without one it is your own model, so nothing costs
+more. None of these beat Swift alone in the evals: see
+[evals/EXPERIMENTS.md](evals/EXPERIMENTS.md).
+
+- `--router`: your model does the routine steps. The strong model takes the first step
+  (reading the task and choosing the approach), the next three steps after LOWE's
+  verification or review rejected the work, and the steps after two tool errors in a row.
+  It also reviews.
+- `--team`: the strong model first explores the project read-only and writes a
+  step-by-step plan; your model carries it out; the strong model reviews the diff.
+- `--best-of N` (with `-p`, in a git repository): the task is solved N times in parallel
+  git worktrees, each candidate's tests are run, and the best one is applied to your
+  project (tests pass > finished normally > changed something > smaller change > cheaper).
+  Your branch, index and files are not touched until the winner is applied. It costs about
+  N times as much.
+
+```bash
+lowe --router --strong-model deep
+lowe --team --strong-model deep -p "add pagination to the /users endpoint"
+lowe --best-of 3 -p "fix the failing date parsing test"
+```
+
+## Remote projects (`--remote`)
+
+```bash
+lowe --remote me@server:/srv/app      # a project on another machine, over SSH
+lowe --remote myserver:app            # a host from ~/.ssh/config; the path from the home folder
+```
+
+LOWE runs here, and its file tools, searches and shell commands run there. It uses one SSH
+connection and a small helper that needs only `python3` on that machine; nothing is
+installed there.
+
+The rules are the same as for a local project: read before edit, GBK and CRLF files stay
+as they are, and `.gitignore` is respected. The same permission checks apply, made here
+before anything is sent. Ctrl+C stops the remote command too.
+
+LOWE keeps a local copy of the project's `LOWE.md`, settings and build files (in
+`~/.lowe/remote/`), so it knows the project's test commands, and its checks run on the
+remote machine. Continue a session with `lowe --remote me@server:/srv/app --resume <id>`.
+
+Limits for now:
+- The file tools only work inside the remote project folder.
+- Changes made by shell commands (rather than LOWE's edit tools) are not shown in the
+  review diff.
+- Helpers, `--team`, `--sandbox` and `--best-of` are not available with `--remote`.
+- Hooks and MCP servers run on your own machine.
+
+Connection options go in `~/.ssh/config`, or in the `LOWE_SSH` environment variable
+(`LOWE_SSH="ssh -p 2222 -i ~/.ssh/work"`).
+
+## MCP tools
+
+LOWE can use tools from [Model Context Protocol](https://modelcontextprotocol.io) servers.
+Add servers to settings in the same format as other MCP clients:
+
+```json
+"mcpServers": {
+  "github": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
+             "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
+                     "npm_config_registry": "https://registry.npmmirror.com"}},
+  "docs":   {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/docs"]}
+}
+```
+
+- LOWE starts them with the session (`MCP: github (26 tools)`), and the model sees their
+  tools as `mcp__github__create_issue` and so on. `/mcp` lists them.
+- `${NAME}` takes a value from an environment variable, so tokens stay out of the file.
+- **Local and network servers.** `command`/`args` start a local (stdio) server; `url` talks to
+  an HTTP one, with `headers` for its token — `lowe mcp add docs --url https://… --header
+  "Authorization=Bearer ${DOCS_TOKEN}"`.
+- **Resources and prompts**, not only tools: a server that offers them gets one extra tool
+  each — `mcp__<server>__read_resource` (by URI) and `mcp__<server>__get_prompt` (by name,
+  with arguments) — with the available URIs and names in the tool's description, so a server
+  with 300 resources does not fill the tool list. Servers with tools only look exactly as
+  before.
+- **Permissions.** Every MCP call asks first. LOWE cannot know what an outside tool
+  changes. Exceptions:
+  - an allow rule (`"allow": ["tool:mcp__docs__*"]`) or `auto` mode lets them run;
+  - `plan` mode refuses them.
+- A repository's shared `.lowe/settings.json` can list servers, but they only start after
+  you trust them once, as with hooks. If the command changes, LOWE asks again.
+
+## VS Code
+
+Install `vscode/lowe-code-0.1.0.vsix` (see [INSTALL.md](INSTALL.md#the-vs-code-extension)),
+then open a project and press `Ctrl+Alt+L` (or use the LOWE button in the title bar or
+status bar). LOWE Code runs in the bottom panel, or in an editor tab beside the code with
+`"lowe.openIn": "editor"`.
+
+- Each time LOWE changes a file, a read-only diff opens beside your code: the file
+  before LOWE's first change in this session, and the file now. Your cursor stays in
+  LOWE's terminal.
+- **LOWE: Review LOWE's changes** lists the session's changed files.
+- Right-click selected code → **Ask LOWE about the selection**.
+- Settings: `lowe.command`, `lowe.args` (e.g. `["--mode", "accept-edits"]`),
+  `lowe.showDiffs`, `lowe.openIn`.
+
+## Hooks
+
+Your own commands before or after tool calls, in settings:
+
+```json
+"hooks": [
+  {"event": "after_tool", "tools": "edit_file|write_file", "command": "npx prettier --write \"$LOWE_FILE\""},
+  {"event": "before_tool", "tools": "bash", "command": "python check_command.py"}
+]
+```
+
+A `before_tool` hook that fails blocks the call. An `after_tool` hook's output is shown to
+the model. Hooks get `LOWE_TOOL`, `LOWE_TOOL_ARGS`, `LOWE_FILE` and `LOWE_PROJECT`. Hooks
+from a repository's shared `.lowe/settings.json` only run after you trust them once.
+
+## Permission modes (`--mode`)
+
+| Mode | Reading | Editing files | Shell commands |
+|---|---|---|---|
+| `ask` (default) | runs | asks | routine work in the project runs; serious commands ask (below) |
+| `accept-edits` | runs | runs | routine work runs; serious commands ask |
+| `plan` | runs | refused | known-safe only; LOWE proposes a plan and you approve it before anything changes |
+| `auto` | runs | runs | runs |
+
+**Serious commands** (asked about in `ask` and `accept-edits`):
+- using the network: `curl`, `ssh`, `git push`, and `npx`, which downloads and runs a
+  package;
+- installing or removing packages;
+- deleting files;
+- stopping processes;
+- changing system or program settings;
+- publishing;
+- hidden code, such as encoded commands, `eval`, or inline code that writes files or
+  connects to the network.
+
+Looking around (`netstat`, `ps`, `--help`, logs) and running the project's own scripts,
+builds and tests run without a question.
+
+Questions take **one key**: `y` yes, `a` yes and don't ask again, `n` no. What "always"
+covers depends on the risk:
+- most commands: that kind of command (`netstat`, `npm run`);
+- network commands: that site (`curl` to `wttr.in`);
+- deleting, installing or changing the system: only that exact command.
+
+`"askEveryCommand": true` in settings brings back a question for every command that is
+not read-only.
+
+In **every** mode, LOWE asks first for:
+- dangerous commands: `rm -rf` on a root, home or whole folder, `sudo`, `git push --force`,
+  `git reset --hard`, `git clean -f`, disk tools, piping a download into a shell,
+  printing environment variables or secrets;
+- files that usually hold secrets (`.env`, `*.pem`, `id_rsa`, `.ssh/`, `.npmrc`, ...);
+- anything outside the project folder.
+
+Without a terminal (for example in a script), such actions are refused, never run.
+
+## Settings
+
+| File | For |
+|---|---|
+| `~/.lowe/settings.json` | you, everywhere |
+| `<project>/.lowe/settings.json` | the team (commit it) |
+| `<project>/.lowe/settings.local.json` | you, in this project (do not commit) |
+
+Later files add to earlier ones. Every key:
+
+| Key | Default | | Shared file? |
+|---|---|---|---|
+| `defaultMode` | `ask` | `ask`, `accept-edits`, `plan` or `auto` | not `auto` |
+| `permissions` | | `allow`, `ask`, `deny` rule lists (below) | allow: once trusted |
+| `language` | system | `zh` or `en` | no |
+| `budget` | `{"cny": 1}` | per task: `cny` and/or `tokens`; `0` = no limit | yes |
+| `fallback` | Swift → Steady → Focus → Wide | LOWE models to continue on, or `false` | no |
+| `strongModel` | your model | for `--router` / `--team` | no |
+| `autoModel` | off | `true` or a list of LOWE models (`--auto-model`) | no |
+| `autoLearn` | `true` | lessons and skills after tasks | may only turn it off |
+| `knowHow` | `true` | built-in know-how | yes |
+| `askEveryCommand` | `false` | ask before every command that is not read-only | may only turn it on |
+| `collectTraining` | `false` | save solved tasks as training data | no |
+| `sandbox` | `python:3.12-slim`, `bridge` | `image`, `network`, `mounts`, `env` for `--sandbox` | no |
+| `hooks` | | commands before or after tools (see Hooks) | once trusted |
+| `mcpServers` | | MCP servers (see MCP tools) | once trusted |
+
+`lowe web` reads `~/.lowe/settings.json` only (`language`, `fallback`, `knowHow`).
+
+```json
+{
+  "defaultMode": "accept-edits",
+  "permissions": {
+    "allow": ["bash:npm run *", "edit:src/**"],
+    "ask":   ["tool:write_file"],
+    "deny":  ["bash:git push*", "read:secrets/**"]
+  },
+  "sandbox": { "image": "python:3.12-slim", "network": "bridge" },
+  "budget": { "cny": 0.5 },
+  "fallback": ["steady", "focus"],
+  "strongModel": "deep"
+}
+```
+
+Rules are `bash:<command pattern>`, `edit:<path glob>`, `read:<path glob>` or
+`tool:<tool name>`. For chained commands (`a && b`), an allow rule must match every part.
+
+For safety, a repository's shared `.lowe/settings.json` cannot turn on `auto` mode, pick
+the sandbox image, or set `fallback` or `strongModel` (they decide where your code is sent
+and what it costs), and its allow rules only work after you trust them once.
+
+## Sandbox (`--sandbox`)
+
+Needs Docker Desktop (Windows, macOS) or Docker Engine (Linux). Each command runs in a
+fresh container that only sees the project folder (at `/workspace`). Set
+`"network": "none"` to cut off the internet. If Docker Hub is slow or blocked, set the
+image to a mirror you trust in your own settings (for example a company registry).
+
+## Privacy
+
+Everything stays on your machine, except what the model needs to see, which goes to the
+provider of the model in use. With fallback that can be another provider whose key you
+set (LOWE says when it switches); `"fallback": false` keeps it to one. Secrets are removed from LOWE's log
+(`~/.lowe/logs/lowe.log`) and audit log (`~/.lowe/audit.log`, one line per permission
+decision). The values of secret environment variables (names containing KEY, TOKEN,
+SECRET, PASSWORD) are also removed from command output before it reaches the model.
+In `lowe web`, those values and known key formats (`sk-...`, `AKIA...`, private keys) are
+removed from messages and uploaded files before they are stored or sent; the rest of the
+code is kept exactly as written.
+
+The web app's Markdown, sanitising and code colours come from marked (MIT), DOMPurify
+(Apache-2.0 / MPL-2.0) and highlight.js (BSD-3-Clause), saved in `lowe_web/static/vendor`
+with their licences, so the page loads nothing from the internet.
+
+With `--remote`, the project's files and command output go from that machine to yours
+over SSH, and from yours to the model provider as above. With MCP servers, what the model
+sends to a tool goes to that server (often a local program, sometimes a web service it
+calls).
+
+## Troubleshooting
+
+Installing: see [INSTALL.md](INSTALL.md#troubleshooting). Using:
+
+| Problem | Fix |
+|---|---|
+| A task stops with "budget reached" | Raise it: `--budget-cny 3`, or `"budget": {"cny": 3}`. `/cost` shows what was spent. |
+| "insufficient balance" / "invalid key" | Top up or fix the key. With another provider's key set, LOWE continues there by itself. |
+| LOWE runs the wrong test command | Edit the `## Commands` section of `LOWE.md` in the project. |
+| LOWE keeps asking before the same command | Choose "always" when asked, or add `"allow": ["bash:npm run *"]`. |
+| Chinese files come back garbled | Should not happen: LOWE reads UTF-8, then GB18030 (GBK), and writes back in the same encoding and line endings. Please report it with the file. |
+| `lowe web` shows "Open the link that lowe web printed" | Open the link with `?token=` that the terminal shows; `lowe web --new-link` makes a new one. |
+| Ctrl+C does nothing on Windows | Update; LOWE turns Ctrl+C back on at start. In an IDE terminal, try Windows Terminal. |
+| An MCP server is listed as "not started" | Run its command by hand to see the error; check `/mcp`. |
+
+## Develop
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e ".[dev]"
+.venv/Scripts/python -m pytest          # offline tests (fake model)
+.venv/Scripts/python -m pytest -m live  # real DeepSeek, Docker, SSH, MCP, Edge and VS Code
+.venv/Scripts/ruff check . && .venv/Scripts/mypy
+cd vscode && npm install && npm test    # the VS Code extension, in the installed VS Code
+```