📖 中文文档：README_zh.md

A coding agent written entirely in the V language, implementing a ReAct-style agent loop (LLM ↔ tools) in a terminal CLI. This is the long-term V codeAgents in V project; Phase 1 (current) hardens the tool layer so the agent is safe to use for editing real code.

• ReAct loop: the LLM requests tool calls; the agent executes them and feeds results back until the model returns a final answer.

• Built-in tools:

  • read_file — paginated text read.
  • write_file — write/overwrite (gated by VCA_ALLOW_WRITE).
  • search_files — regex search (regex.pcre), skips large/binary files.
  • terminal — run a shell command (gated by VCA_ALLOW_EXEC).
  • list_files (Phase 12) — list files/dirs under a path (like ls/find), with optional glob pattern filter and recursive toggle. Read-only, no write/exec permission needed — handy for the agent to map project structure.
  • web_search (Phase 12) — query the web via DuckDuckGo and return result titles + URLs. Uses the system curl, so it is gated by VCA_ALLOW_EXEC (same as terminal); offline or missing curl yields a clear error, never a hang.
  • git (Phase 14) — run a git subcommand in the project (status, diff, log, add, commit -m "...", branch, ...). Gated by VCA_ALLOW_EXEC like terminal; destructive ops (push, reset --hard, clean, rebase, branch -D, ...) route through the same confirm() gate, so they never run blind — and commit without -m is rejected (no editor in this env). Handy for the agent to inspect and record its own work.
  • Syntax highlighting (Phase 15) — a tiny, dependency-free syntax module highlights V / Go / JavaScript / HTML / bash code, emitting HTML (for the Web UI) or ANSI (for the CLI). In the Web chat, fenced code blocks (v … ) are colourised; all output is HTML-escaped to prevent injection.
  • patch (Phase 1) — precise in-place edit:
    • mode=exact: replace old_string→new_string (one match required, or set replace_all=true).
    • mode=lines: replace lines [start,end] (1-based, inclusive) with replacement.
    • Respects dry_run (report only) and interactive confirmation.
  • vet / fmt / test (Phase 1) — run v vet . / v fmt -w . / v -silent test . on a target (default = whole project).

• Provider-agnostic chat client (OpenAI / OpenRouter / Ollama / llama.cpp compatible).

• Offline mock provider for testing with no API key.

• SQLite-backed session persistence (resumable transcript).

• Append-only event log under data/vaiv.log.

• Safety by default (Phase 1):

  • Writes/exec gated by flags (VCA_ALLOW_WRITE / VCA_ALLOW_EXEC).
  • Dangerous terminal commands (rm -rf, git push, dd, kill, …) are blocked unless approved (VCA_AUTO_YES=1) or confirmed interactively.
  • dry_run mode: patch/fmt report intent without modifying files.
  • Tool output is truncated (VCA_RESULT_LIMIT, default 8000 bytes) so a huge file/command can't blow up the context window.

• Memory & context (Phase 2):

  • Cross-session memory table in SQLite (MemoryRow): user prefs, project facts survive restarts and are injected into the system prompt on each run.
  • Session retrieval: recall(query) keyword search over stored memory.
  • Context compression: when the transcript exceeds VCA_COMPACT_THRESHOLD messages, the middle turns are summarized (LLM when online, deterministic extractive fallback offline) while the system prompt and last keep_recent messages stay verbatim — key info is never lost.
  • Configurable system prompt via VCA_SYSTEM / system: in config.yaml.

• Multi-agent orchestration (Phase 3): ✓

  • A request is decomposed by a Planner into ordered/parallel SubTasks. With a real LLM it asks the model for a JSON plan; offline (mock) it uses a deterministic heuristic (splits numbered/bulleted lists, else one task).
  • Each SubTask runs in an isolated sub-agent (own ReAct loop + own tool context) via run_parallel (goroutines + channel, dependency-ordered waves) or run_sequential.
  • A Reducer merges sub-results into one answer; a failed subtask is reported inline and does not abort the run (failure isolation).
  • Enable with VCA_PARALLEL=1 (or parallel: true in config.yaml).

• Resilience (Phase 6): LLM call retry with exponential backoff (network/5xx/429), configurable per-request timeout, and a per-tool consecutive-failure guard that aborts runaway loops (≥3 in a row). 4xx is not retried (bad request / auth).

• Run telemetry & machine-readable output (Phase 7):

  • Every run populates Agent.last_run (provider, model, steps, tool_calls, per-tool counts, errors, duration_ms, finish) — never written into the transcript, so persistence stays clean.
  • CLI flags: --json emits {"ok":true,"final":"...","stats":{...}} (or an error envelope) for CI / jq; --stats prints a one-line human summary after the answer. Both are offline-testable under the mock provider.

• Persistent telemetry & observability (Phase 8): ✓ (v0.5.3)

  • Token usage (P8.1): every run now captures usage{prompt_tokens, completion_tokens} from OpenAI-compatible endpoints (mock = 0). Real providers (e.g. Shangtang, OpenAI) fill it in; missing usage degrades to 0.
  • Persistent store (P8.2/P8.3): each run — single, REPL turn, parallel orchestration, and web chat — is appended to an independent SQLite file data/vaiv-telemetry.sqlite (separate from session.sqlite and vaiv-web.sqlite, never disturbed by session replace()).
  • CLI report (P8.4): vaiv --report prints a human aggregate (total runs, total tokens, duration, by-provider breakdown, recent runs); vaiv --report json (or --report-json) emits a machine-readable JSON object. Both read only the local telemetry DB, so they work fully offline.
  • Web dashboard (P8.5): vaiv-web gains GET /metrics (dark-themed dashboard with run/token/duration cards + per-provider breakdown) and GET /api/metrics (JSON), aggregating the same persisted store.
  • Tests (P8.6): telemetry_store_test.v (save/count/summarise/last_n/reset) and llm_test.v (usage parse present & absent) lock in the behaviour.

• Conventions module — user principles & habits (Phase 9): ✓ (v0.6.0)

  • The agent can create and maintain the user's principles & habits as Markdown files, in two scopes:
    • system: ~/.vaiv/conventions.md (applies to every vaiv project)
    • project: <project_root>/.vaiv/conventions.md (committed, team-shared)
  • Three built-in tools: convention_add(layer, category, text), convention_list(layer), convention_remove(layer, id). add is gated by VCA_ALLOW_WRITE; remove is destructive and requires confirmation (VCA_AUTO_YES=1 to auto-approve, matching the terminal-tool policy).
  • Proactive injection: at the start of every run(), the merged system+project conventions are injected into the system prompt (same mechanism as Phase 2 memory, never persisted into the transcript), so the agent follows the user's principles without being reminded each time.
  • Learning triggers: passive (user says "记住：…" → agent calls convention_add) and active (agent notices repeated corrections → proposes saving, but confirms first to avoid mis-recording).
  • Tests (P9.4): conventions_test.v (add/list/remove, auto-numbering, cross-layer isolation, run() injection) and tools_test.v (convention_* tool end-to-end incl. remove-confirmation gate).
  • Learning reminders (Phase 9.5): after a successful turn that actually used tools, vaiv prints a one-line [tip] reminding you to save a useful principle / habit / gotcha via convention_add — so future sessions take fewer detours. The nudge is non-nagging: it only appears while your convention store is still sparse (< 3 entries total across both layers), and it names the tools that fired this run. It is never shown in --json mode. (conventions_learning.v + conventions_learning_test.v.) Consistent on CLI and Web: the Web sync endpoint appends the [tip] line to the reply; the streaming endpoint emits a separate event: tip SSE event that the front-end renders as a distinct green hint bubble (.msg.tip). Web "save as convention" button: the tip bubble carries a "存为约定" button that opens an inline form (scope / category / text) and POSTs to /api/convention to persist immediately — manual-confirm, no auto-save, and it shares the same store as the convention_add tool so it takes effect on the next run.

• Self-update (Phase 10): ✓ (v0.6.1)

  • vaiv update self-updates the binary without involving the LLM. It delegates to scripts/vaiv_update.vsh (form C), which can also run standalone via v run scripts/vaiv_update.vsh.
  • Flow: locate repo root → check git status (abort on uncommitted changes unless --force) → back up old binaries to .bak → git pull --ff-only → recompile bin/vaiv + bin/vaiv-web → run v test → rollback to .bak on any failure → print the new version from v.mod.
  • Safety: never git reset --hard, never delete user files; backups are renames (.bak), rollback restores them. The V compiler (~/v) is never touched — only vaiv source is pulled and rebuilt.
  • Flags: vaiv update --force (skip the uncommitted-changes guard), vaiv update --dry-run (print the steps without touching anything), vaiv update --self-test (run the script's internal pure-function tests).
  • Verified: uncommitted-changes guard aborts with a clear message; --dry-run prints the full pipeline correctly; script self-tests pass (4/4).

• Session management & config introspection (Phase 11): ✓ (v0.6.1)

  • Multiple sessions: each conversation is stored in its own SQLite file under data/sessions/<name>.sqlite, so you can keep several threads side-by-side. Use vaiv --session <name> "prompt" (or --session <name> alone for REPL) to talk to a specific one; the default is default.
  • vaiv sessions lists all stored sessions with their message counts.
  • vaiv export [name] dumps a session's transcript as Markdown (system prompts are skipped), handy for archiving or pasting elsewhere.
  • vaiv config prints the fully-resolved configuration (file → env → defaults merge) with the API key masked, so you can verify exactly what the agent will run with. All four sub-commands run without the LLM.

• Self-issue structured logging & auto-recording (Phase 19 tier-0): ✓

  • Structured problem recording: vaiv can capture runtime issues into an independent SQLite file data/vaiv-selfissues.sqlite (separate from telemetry and session stores), forming the observation layer for the self-evolution roadmap.
  • SelfIssue fields: severity (crash/error/warn/info), kind (llm_error/tool_error/…), title, detail, source, resolved.
  • Auto-recording during agent runs: when a SelfIssueStore is attached via with_selfissues(), the agent automatically records problems without interrupting execution:
    • LLM streaming error → severity: 'error', kind: 'llm_error'
    • LLM chat error → severity: 'error', kind: 'llm_error'
    • 3 consecutive tool failures → severity: 'error', kind: 'tool_error'
    • max_steps exceeded without finishing → severity: 'warn', kind: 'max_steps'
  • CLI introspection: vaiv selfissues list [severity], vaiv selfissues add <sev> <kind> <title> [detail], vaiv selfissues resolve <id>, vaiv selfissues retrospective.
  • Observation-only: never modifies vaiv's own source (zero risk). Higher tiers (automated fix proposals, gated self-evolution) are future roadmap items.

• Model registry & manual switching (Phase 16): ✓ (v0.7.1)

  • A dedicated entry point for managing models, so you no longer have to hand-edit config.yaml. Models live in .vaiv/models.yaml (a separate file, so your hand-written config.yaml comments stay intact).
  • vaiv models lists all configured models with an * marking the active one.
  • vaiv models add <provider> <model> [base_url] [api_key] appends a model and persists it; the first model added becomes active automatically.
  • vaiv models use <n> sets the active model (tried first; falls back across enabled models on failure).
  • vaiv models remove <n> / vaiv models enable <n> / vaiv models disable <n> mutate the registry.
  • In the REPL: /models lists, /use <n> hot-switches for the current session only (does not persist).
  • The Web UI has a 模型 (Models) page at /models: add / delete / toggle / one-click switch, all driven by the same .vaiv/models.yaml.

• Session data integrity: Session.replace() wraps saves in BEGIN/COMMIT/ROLLBACK; if save() or COMMIT fails, the transaction is automatically rolled back, preventing partial-write corruption of the transcript.

• Optional Web UI (Phase 4):

  • A veb-based web front-end that reuses the same agent core (no duplicate ReAct loop). Built as a separate cmd/web entry.
  • Session list, "new chat", per-session transcript view, and an SSE-streamed chat (each assistant delta + tool call is pushed live over Server-Sent Events; falls back to a sync POST). SSE exit safety: uses AbortController + beforeunload to automatically cancel streaming on page leave, with a browser confirmation dialog when a stream is active.
  • Bilingual UI: translations/zh.tr + translations/en.tr (Chinese default), loaded by veb's veb.tr.
  • SQLite-backed session store (webstore.v, file data/vaiv-web.sqlite) — web sessions survive a server restart. The web DB is deliberately isolated from the CLI's data/session.sqlite (different tables, different file).
  • Bilingual UI with live switching: a 中文 / EN switch in the top bar sets a vaiv_lang cookie and reloads; GET /lang?l=zh|en&from=<path> flips the language and redirects back. Templates pull strings from translations/zh.tr + translations/en.tr via veb.tr(lang, key).
  • Run offline: with no API key it auto-uses the mock provider, so the whole UI (create → chat → stream) works with v -o and curl.

Requires V 0.5.x at ~/v (or on PATH).

# CLI
v -o bin/vaiv .
./bin/vaiv "read v.mod and tell me the module name"

# Web UI (Phase 4)
v -o bin/vaiv-web cmd/web
./bin/vaiv-web            # open http://localhost:3003/

A self-contained V script installs the two binaries into a custom prefix and uninstalls them safely:

# install into ~/.local/bin (default); builds from the current repo tree
v run scripts/vaiv_install.vsh install
# custom prefix + explicit V compiler:
v run scripts/vaiv_install.vsh install --prefix /opt/vaiv --v ~/v/vnew
# clone a fresh copy from the repo URL instead of using the cwd tree:
v run scripts/vaiv_install.vsh install --repo https://github.com/ovlo/vaiv --prefix ~/apps

# uninstall — safe by default: renames to .bak, never deletes
v run scripts/vaiv_install.vsh uninstall
v run scripts/vaiv_install.vsh uninstall --prefix /opt/vaiv --purge   # truly remove

Flags: --prefix DIR (install root, binaries → DIR/bin; default ~/.local), --repo URL (git URL to clone when not already inside the repo), --v PATH (V compiler; defaults to the v on PATH), --force (overwrite without a .bak), --purge (uninstall: actually delete instead of .bak), --dry-run (print every step, touch nothing). Add DIR/bin to your PATH after install.

A self-contained V script produces a minimal .deb that installs vaiv to /usr/bin/vaiv. It uses dpkg-deb (present on every Debian/Ubuntu host) — no fpm/ruby needed. Package name + version are read from v.mod automatically.

# build bin/vaiv (if missing) and produce build/vaiv_<ver>_amd64.deb
v run scripts/build_deb.vsh
# preview every step without writing anything
v run scripts/build_deb.vsh --dry-run
# cross-target / custom maintainer
v run scripts/build_deb.vsh --arch arm64 --maintainer "You <you@x.io>"

# inspect and install
dpkg-deb -I build/vaiv_0.7.2_amd64.deb     # show control metadata
dpkg-deb -c build/vaiv_0.7.2_amd64.deb     # list files that will be installed
sudo dpkg -i build/vaiv_0.7.2_amd64.deb    # install

What the script does: it stages a tiny FHS tree (<name>_<ver>_<arch>/DEBIAN/control + usr/bin/vaiv), writes a control file (Package/Version/Architecture/Depends: libc6), then runs dpkg-deb --build --root-owner-group. The package ships only the binary — vaiv's runtime data (data/, ~/.vaiv) is created on first run, not bundled. The binary is dynamically linked against glibc (libc/libm/libmvec), so the lone Depends: libc6 (>= 2.31) is sufficient on any modern Debian/Ubuntu.

Existing staging trees are renamed to .bak (never deleted), per the project's "never delete" convention. Output goes to build/ by default (--output DIR to change).

export VCA_API_KEY=sk-...            # OpenAI or OpenRouter key
export VCA_MODEL=openai/gpt-4o-mini  # or openrouter/...
export VCA_PROVIDER=openrouter        # or openai
./bin/vaiv "refactor main.v to use a config struct"

Ollama: export VCA_PROVIDER=ollama ./bin/vaiv "explain this module" llama.cpp server (e.g. ./server -m model.gguf): export VCA_PROVIDER=llamacpp ./bin/vaiv "summarize tools.v" Both are configured under .vaiv/config.yaml (ollama: / llamacpp: blocks) and expose an OpenAI-compatible /v1 API, so the same client code path is used.

VCA_ALLOW_WRITE=0       # disable write_file / patch (default on)
VCA_ALLOW_EXEC=0        # disable terminal / vet / fmt / test (default on)
VCA_AUTO_YES=1          # auto-approve risky actions (skip confirmation)
VCA_DRY_RUN=1           # patch/fmt report intent, do not modify files
VCA_RESULT_LIMIT=4000   # cap tool output bytes (default 8000)
VCA_COMPACT_THRESHOLD=40 # compress transcript beyond N msgs (0 = off)
VCA_PARALLEL=1           # decompose request into subtasks, run concurrently
VCA_SYSTEM="You are vaiv, a V coding agent." # override system prompt

vaiv --json "read v.mod"   # machine-readable: {"ok","final","stats"}
vaiv --stats "read v.mod"  # human one-line run summary after the answer
# also work in parallel mode: VCA_PARALLEL=1 vaiv --json "1. do A\n2. do B"
vaiv --report              # aggregate telemetry: total runs, tokens, by-provider
vaiv --report json         # same, as a JSON object (CI / jq friendly)
# Note: --report reads only the local data/vaiv-telemetry.sqlite; it needs
# no API key and works fully offline.

vaiv --session work "refactor main.v"   # talk to the 'work' session (creates if new)
vaiv --session work                     # continue 'work' in REPL mode
vaiv sessions                           # list all sessions with message counts
vaiv export work                        # dump 'work' transcript as Markdown to stdout
vaiv export work > work-chat.md         # ... redirected to a file
vaiv config                             # print resolved config (api key masked)
vaiv models                             # list configured models (* = active)
vaiv models add shangtang m1 https://x/v1   # add a model (persists to .vaiv/models.yaml)
vaiv models use 2                       # make model #2 the active one
# Each session lives in its own file: data/sessions/<name>.sqlite
# The default session is 'default' (legacy data/session.sqlite is migrated there).

vaiv update                # pull latest, recompile bin/vaiv + bin/vaiv-web, run tests
vaiv update --force        # ignore uncommitted changes (risk: may merge over local work)
vaiv update --dry-run      # show the steps without pulling / compiling
# The updater aborts if you have uncommitted changes (never overwrites your work).
# On any build/test failure it restores the previous binaries from .bak.

System config lives in the repo at .vaiv/config.yaml (committed; secrets via env). Resolution order: .vaiv/config.yaml → VCA_* env → built-in defaults. When no API key is present for a remote provider, it auto-downgrades to mock.

All runtime state is anchored to the vaiv project root (the directory containing v.mod), regardless of the directory you launch the binary from. This means ./bin/vaiv and cd bin && ./vaiv both write to the same place — never into bin/. The project root is derived from the executable path (<root>/bin/vaiv → <root>) and confirmed by the presence of v.mod; if vaiv is installed outside the repo, it falls back to the current directory.

data/session.sqlite   # CLI transcript (persists across turns & restarts)
data/vaiv.log         # append-only event log
data/vaiv-web.sqlite  # Web UI sessions (Phase 4, isolated from CLI)

~/.vaiv/conventions.md            # system-level user principles (Phase 9)
<root>/.vaiv/conventions.md       # project-level principles (Phase 9, committable)

bin/ is a build-artifact directory (git-ignored) and intentionally holds no runtime data.

v.mod
main.v                 # CLI entry (module main)
.vaiv/config.yaml       # system config
agent/                  # module agent
  types.v config.v llm.v tools.v agent.v session.v logger.v
  confirm.v             # dangerous-command detection + interactive confirm (Phase 1)
  execsafe.v           # Phase 21: hardened bash-exec module (policy gate, no shell, audit)
  patch.v               # precise patch tool (Phase 1)
  devtools.v            # vet / fmt / test tools (Phase 1)
  compress.v            # context compression (Phase 2)
  session.v             # SQLite: transcript + MemoryRow (Phase 2)
  orchestrator.v        # planner + sub-agent runtime + reducer (Phase 3)
  webapi.v             # Phase 4: veb handlers (REST + SSE + pages)
  webstore.v           # Phase 4: SQLite-backed web session store (data/vaiv-web.sqlite)
  telemetry.v          # Phase 7/8 run metrics
  telemetry_store.v    # Phase 8 persistent telemetry store
  conventions.v        # Phase 9: user principles & habits (system+project)
  *_test.v              # unit tests per module (incl. webapi_test.v + webapi_http_test.v)
cmd/web/               # Phase 4 entry: veb WebApp bootstrap
  main.v
scripts/
  vaiv_update.vsh       # Phase 10: self-update logic (also runnable via `v run`)
  vaiv_install.vsh      # Phase 17: install/uninstall (safe .bak rename)
  build_deb.vsh         # Phase 21 follow-up: build a .deb via dpkg-deb
web/
  templates/            # veb HTML templates (index, new_session, session, about)
  static/               # app.js (SSE client) + style.css
translations/          # zh.tr + en.tr (veb i18n, loaded from cwd)
data/                   # runtime: session.sqlite + vaiv.log (git-ignored)
agents.md               # phased plan + acceptance criteria

v fmt -w . && v vet . && v -silent test .

• Phase 2: memory + context compaction. ✓
• Phase 3: multi-agent orchestration. ✓
• Phase 4: optional veb web UI. ✓ (v0.4.1)
• Phase 6: LLM retry + timeout + tool-failure guard. ✓ (v0.4.7)
• Phase 7: run telemetry + machine-readable --json/--stats. ✓ (v0.5.0, hardened v0.5.2)
• Phase 8: persistent telemetry (token usage, SQLite store, --report, web dashboard, tests). ✓ (v0.5.3)
• Phase 9: conventions module — agent-maintained user principles & habits (system + project layers, injected into system prompt). ✓ (v0.6.0)
• Phase 10: self-update (vaiv update) — pull + recompile + test with safe rollback, no LLM involved. ✓ (v0.6.1)
• Phase 11: session management (--session, vaiv sessions, vaiv export) + config introspection (vaiv config). ✓ (v0.6.1)
• Phase 21: hardened bash-exec module (execsafe: policy-gated, shell-free execvp, audit log) + CLI ! command + .deb build script. ✓ (v0.7.2)