wuyang
124 lines
3.5 KiB
Markdown
124 lines
3.5 KiB
Markdown
# 开发与验证
|
|
|
|
中文 · [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. 在验证完成前保留上一镜像和部署备份。
|