# Development and verification

[中文](development.zh-CN.md) · English

## Repository layout

```text
agent_platform/
  runtime/        Agent API, loop, context, model transport, and tools
  gateway/        Authenticated workspace and file service
  auth.py         Internal service and signed identity verification
  models.py       Public model catalog and server-side budgets
  store.py        Run events, memories, and plans
docker/
  web/            Open WebUI components and reproducible patch set
  *.Dockerfile    Web, Runtime, Gateway, and Workspace images
docs/
  site/           Static source for /doc/
deploy/           Production Compose files and SSH override
e2e/              Deterministic full-stack verifier and fake provider
scripts/          Verification, evaluation, audit, and secret helpers
tests/            Unit and real Docker integration tests
```

## Local environment

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
cp .env.example .env
./scripts/init-secrets.sh
```

Keep real provider credentials in a protected local environment or deployment
file. Never add them to Git, Docker build arguments, frontend code, test
fixtures, or logs.

Build the user workspace, then start the stack:

```bash
docker compose --profile build-only build workspace-image
docker compose up --build
```

Open <http://localhost:3000>. New registrations have the `pending` role until
approved by the bootstrap administrator.

## Fast feedback

```bash
.venv/bin/ruff check agent_platform tests e2e
.venv/bin/ruff format --check agent_platform tests e2e
.venv/bin/pytest
```

Unit tests are deterministic and do not require a model provider.

## Real Docker integration

```bash
docker build -f docker/workspace.Dockerfile \
  -t k1412-agent-workspace:test .
RUN_DOCKER_INTEGRATION=1 \
  .venv/bin/pytest tests/test_docker_workspace.py
```

The test creates unique containers, networks, and volumes and removes only
those resources in cleanup.

## Full-stack E2E

```bash
./scripts/verify-e2e.sh
```

The script builds a disposable six-service stack, uses a deterministic model
stub, performs authentication and isolation checks, and removes the stack and
test volumes on exit.

## Live Agent evaluation

```bash
set -a
source /path/to/protected/provider.env
set +a
.venv/bin/python scripts/eval-live-work.py --model deepseek-v4-pro
```

Use `--keep-workspace` only when inspecting a failed case; remove that uniquely
named evaluation workspace afterward.

## Image audit

```bash
./scripts/audit-images.sh
```

The audit requires consistent Python environments and no fixable
High/Critical vulnerabilities in the finished images. Web also receives a
Python dependency audit.

## Documentation portal

`docs/site/` is dependency-free static HTML, CSS, JavaScript, and JSON. It is
copied into `/app/build/doc` by `docker/web.Dockerfile` after Open WebUI's
frontend build completes.

Validate it locally with:

```bash
python3 -m http.server 4173 --directory docs/site
```

The production path is `/doc/`; all internal assets therefore use relative
URLs. Keep the Markdown documents and portal content aligned in the same
commit. Add experiment cards through `docs/site/experiments.json`.

## Change checklist

Before pushing:

1. keep unrelated working-tree changes untouched;
2. update architecture or behavior documentation;
3. add deterministic tests for policy changes;
4. run unit and formatting checks;
5. run Docker integration for workspace/Gateway changes;
6. run E2E for public model, auth, loop, or file-delivery changes;
7. audit every rebuilt image;
8. use immutable production image tags;
9. verify public health and one representative user flow;
10. retain the previous image and deployment backup until verification passes.