wuyang
130 lines
3.6 KiB
Markdown
130 lines
3.6 KiB
Markdown
# Development and verification
|
|
|
|
## 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.
|