docs: publish architecture and experiment portal

2026-07-26 21:03:23 +08:00
parent 4eb915283d
commit 688ddec1fe
17 changed files with 3582 additions and 56 deletions
@@ -0,0 +1,129 @@
+# 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.