开发与验证

中文 · English

仓库结构

agent_platform/
  runtime/        Agent API、Loop、上下文、模型传输和工具
  gateway/        已鉴权的工作区和文件服务
  auth.py         内部服务与签名身份验证
  models.py       公开模型目录与服务端预算
  store.py        运行事件、记忆和计划
docker/
  web/            Open WebUI 组件与可复现补丁集
  *.Dockerfile    Web、Runtime、Gateway 和 Workspace 镜像
docs/
  site/           /doc/ 的静态源码
deploy/           生产 Compose 文件和 SSH Override
e2e/              确定性全栈验证器与假 Provider
scripts/          验证、评测、审计和密钥辅助脚本
tests/            单元测试与真实 Docker 集成测试

本地环境

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

真实 Provider 凭据必须保存在受保护的本地环境文件或部署文件中。绝不能将其加入 Git、 Docker 构建参数、前端代码、测试 Fixture 或日志。

构建用户工作区并启动服务栈：

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

打开 http://localhost:3000。新注册用户的角色为 pending，直到初始化管理员批准。

快速反馈

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

单元测试是确定性的，不需要模型 Provider。

真实 Docker 集成

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

测试会创建名称唯一的容器、网络和卷，清理时只删除这些测试资源。

完整栈 E2E

./scripts/verify-e2e.sh

该脚本会构建一次性六服务栈，使用确定性模型桩，执行鉴权与隔离检查，并在结束时删除测试栈和测试卷。

真实 Agent 评测

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

只有检查失败用例时才使用 --keep-workspace；检查结束后应删除该名称唯一的评测工作区。

镜像审计

./scripts/audit-images.sh

审计要求 Python 环境依赖一致，并且最终镜像中不存在可修复的 High/Critical 漏洞。 Web 镜像还会接受 Python 依赖漏洞审计。

文档门户

docs/site/ 是不依赖构建工具的静态 HTML、CSS、JavaScript 和 JSON。Open WebUI 前端构建完成后，docker/web.Dockerfile 会将它复制到 /app/build/doc。

本地验证：

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

生产路径是 /doc/，因此所有内部资源都使用相对 URL。Markdown 文档和门户内容必须在同一个 commit 中保持一致。通过 docs/site/experiments.json 添加实验卡片。

变更检查清单

推送前：

不要改动工作树中无关的用户变更；
更新架构或行为文档；
为策略变更添加确定性测试；
运行单元测试和格式检查；
Workspace/Gateway 变更必须运行 Docker 集成测试；
公开模型、鉴权、Loop 或文件交付变更必须运行 E2E；
审计每个重新构建的镜像；
生产环境只使用不可变镜像标签；
验证公网健康状态和一个代表性用户流程；
在验证完成前保留上一镜像和部署备份。

3.5 KiB Raw Permalink Blame History