AGENTS.md · avibe-bot/avibe

Sections

1. 1. Project Overview
2. 2. Design Philosophy and Architecture
3. 3. Runtime Environments
4. 4. Configuration and Routing Model
5. 5. Development Workflow
6. 6. Coding Standards
7. 7. Testing and Validation
8. 8. Git, Security, and Operational Safety
9. 9. Release Workflow

First lines (shown under the repo's MIT license)

# Agent Guidelines for Avibe

This document is the operating manual for coding agents working in this repository.

## 1. Project Overview

Avibe is the local-first Agent OS: one install command turns a machine into the
runtime an agent lives in, and the user operates that runtime through Web or IM
surfaces such as Slack, Discord, Telegram, Feishu/Lark, and WeChat.

Current product shape:

- V2 config-driven service with a Web UI setup wizard and settings pages
- multi-platform message transport with shared core orchestration
- multi-backend agent routing across OpenCode, Claude Code, and Codex
- local Incus-based unified regression environment for real cross-platform verification

## 2. Design Philosophy and Architecture

### Product and Technical Decision-Making

- Start from one coherent user mental model. Avibe absorbs backend and
  implementation differences; users and agents see only what they need to act.
- Establish hard constraints before choosing scope. Build the smallest complete
  solution that works within them, and leave concepts undefined until they have
  a clear responsibility.
- Prefer compatibility, permissive adoption, and subtraction. Add validation,
  metadata, state, or isolation only when it protects a demonstrated outcome.
- Reuse existing ownership and lifecycle before adding mechanisms. Keep the
  path simple and stateless, then optimize from measured evidence.

### Core Rule: Fix at the Highest Appropriate Layer

- If a bug appears on one platform, check whether the same logic exists for the others before patching a platform adapter.
- If a behavior should be shared by multiple backends, prefer the shared core or backend abstraction over a single backend implementation.
- Keep transport/platform details out of core business logic whenever possible.

Decision checklist before writing code:

1. **Scope**: is this platform-specific/backend-specific, or common?
2. **Abstraction**: can the shared base or core layer own this behavior?
3. **Call path**: is the code called from controller/handlers/common flow?
4. **Future-proofing**: would a new platform/backend inherit the correct behavior automatically?

### Codebase Map

- `main.py` - entry point wiring `config.V2Config` into `core/controller.py`
- `core/controller.py` - orchestration and dependency wiring
- `vibe/ui_server.py` and `vibe/api.py` run in a separate process from the
  controller and reach controller-owned state over the internal socket;
  `vibe/api.py` builds its own `AgentAuthService`. In-memory registries therefore
  cannot span IM and Web surfaces: cross-surface exclusion needs an explicit IPC
  hop or a documented per-instance scope. See PR #1417's Known-by-design ledger.
- `core/handlers/` - platform/backend-agnostic business workflows
- `core/message_dispatcher.py` - outbound message routing and reply enhancement flow
- `core/reply_enhancer.py` - file-link and quick-reply prompt injection helpers
- `modules/im/` - IM platform adapters (`slack.py`, `discord.py`, `telegram.py`, `feishu.py`, `wechat.py`) plus shared base classes
- `modules/agents/` - agent backend adapters (`opencode/`, `codex/`, Claude-related modules) plus shared abstractions
- `modules/im/formatters/` - platform-specific formatting built on shared formatter concepts
- `config/` - V2 config, settings, sessions, paths, and compatibility conversion
- `ui/` - React + Vite + TypeScript Web UI
- `scripts/` - operational helpers, including regression testing workflows
- `tests/` - pytest-style unit/integration/regression coverage

### Runtime Data and Important Paths

- default home: `~/.avibe/`
- legacy home: `~/.vibe_remote/` remains a compatibility path and may be a back-symlink to `~/.avibe/`
- logs: `~/.avibe/logs/vibe_remote.log`
- persisted state: `~/.avibe/state/`
- default agent working directory: `_tmp/`
- generated regression metadata: `.runtime/incus-regression/` in the primary checkout

## 3. Runtime Environments

### Local `vibe` Service

Common commands:

- install: `uv tool install avibe-os`
- run: `vibe`
- inspect: `vibe status`
- stop: `vibe stop`

Use local `vibe` for local packaging or CLI behavior checks.

Hard rule:

- **Never restart the local `vibe` service for routine verification.**
- The local `vibe` process may be the coding agent runtime itself; restarting it can interrupt the session.
- **Stop only processes you started, by the pid you recorded.** Never
  pattern-kill (`pkill -f`, `killall`, `pgrep ... | xargs kill`): a test service
  or UI runs the same command line as the user's live `vibe`, even under a
  separate `AVIBE_HOME`, so the pattern also kills the live runtime.
- **Tests and probes must be hermetic by default.** Treat `$HOME`, XDG dirs,
  keychains, CLI config/token stores, running services, browser profiles, and
  cloud accounts as production data unless the user explicitly asks otherwise.
- Any test that reaches write-capable production paths must redirect the whole
  call path to test-owned state and prove a representative write cannot touch
  real local or external user state; `uses_real_paths` tests must remain read-only.
- Unless the user explicitly asks otherwise, use the Incus regression environment for user-facing verification.

### Regression Testing (Incus)

When the user says `回归测试`, update the latest code into the existing **local**
Incus regression environment, preserve accumulated product state unless reset is
explicitly requested, then let the user verify Slack, Discord, Feishu/Lark, and
WeChat behavior.

Entry points:

- default: `./scripts/run_regression.sh`
- direct: `python3 scripts/incus_regression.py up --target master`
- macOS/Lima: `INCUS_CMD="limactl shell avibe-incus-regression -- sudo incus" ./scripts/run_regression.sh`

Hard rules:

- local Incus only for development regression; never use `--remote`, SSH, remote
  tenant projects, demos, or customer/user environments unless explicitly asked
  for remote ops
- use the runner, not raw Incus commands; it owns naming, source sync, state
  preparation, readiness checks, Show Runtime setup, metadata, and cleanup
- `master` is the long-running unified four-platform environment other Sessions
  test on: deploy only the merged default branch to it, keep it online, preserve
  product state, sync source, and restart the service in place; verify an
  unmerged branch on a `worktree` target
- `worktree` targets are temporary isolated environments; delete each one
  explicitly with
  `python3 scripts/incus_regression.py delete --target worktree --slug <slug> --yes`
  when merged, abandoned, or stale
- before updating, restarting, or deleting any regression environment, check its
  hold with `status` or `reconcile`, since holds do not stop `up` or `down`; if
  held, tell the user who holds it and why, and do not proceed or offer a
  one-click delete. Long-running work must hold its environment for as long as
  it runs.
- `reconcile` reports every worktree environment held by Incus, including
  environments created outside the runner, and only forgets metadata for
  environments that are no longer present. It never deletes an environment.
- a metadata row is dropped only after a complete, readable listing shows that
  the daemon holds neither its project nor instance and the row is not a live
  `up` reservation
- never use `--reset-config` / `--reset-all`, wipe regression state, or overwrite
  Avibe Cloud pairing / `remote_access` just to make probes pass unless asked
- after any regression update, verify service health before reporting success

The runner's reconciliation, reservation, daemon ownership, and state lookup
semantics live in `docs/regression/README.md`. Read that document when changing
the runner or diagnosing metadata cleanup.

## 4. Configuration and Routing Model

Persistent configuration is centered on `config/v2_config.py` and the Web UI.

High-level V2 config areas:

- platform config: Slack / Discord / Telegram / Feishu / WeChat credentials and switches
- runtime config: default cwd, log level, and related runtime behavior
- agent config: per-backend enablement and CLI paths
- UI config: setup host/port and Web UI behavior