docs: add complete Chinese documentation

2026-07-26 21:32:12 +08:00
parent 66109235e2
commit e2e7a7ba37
24 changed files with 1251 additions and 14 deletions
@@ -0,0 +1,123 @@
+# 开发与验证
+
+中文 · [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. 在验证完成前保留上一镜像和部署备份。