# 开发与验证

中文 · [English](development.md)

## 仓库结构

```text
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 集成测试
```

## 本地环境

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

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

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

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

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

## 快速反馈

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

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

## 真实 Docker 集成

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

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

## 完整栈 E2E

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

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

## 真实 Agent 评测

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

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

## 镜像审计

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

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

## 文档门户

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

本地验证：

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

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

## 变更检查清单

推送前：

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