diff --git a/AGENTS.md b/AGENTS.md
index 211bc7d..9c7c9c4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -127,6 +127,91 @@ Set-Location D:\www\gs-sport-era; powershell -ExecutionPolicy Bypass -File .\scr
 
 - `admin/`、`uniapp/`、`pc/`、`docker/`、`python/`、`qa/`、`scripts/` 等非 `server/` 源码改动必须提交 commit，但不要因此自动同步服务器。`docs/` 等说明文档不触发自动提交或服务器同步。
 
+## 测试环境命令与 Docker 运行清单
+
+### Git 同步
+
+在服务器以 `ubuntu` 用户执行日常 Git 操作；只有 Docker 命令使用 `sudo`：
+
+```bash
+cd /www/wwwroot/test-server.sbnews.net
+git remote -v
+git fetch origin dev.1.0.0
+git pull --ff-only
+```
+
+如果 `.git/objects` 权限异常，只修复 Git 元数据，不要递归修改整个项目：
+
+```bash
+sudo chown -R ubuntu:ubuntu .git
+sudo chmod -R u+rwX .git
+```
+
+如果 `.playwright-mcp/*` 等未跟踪生成文件阻塞拉取，先移动到临时目录，再执行 `git pull --ff-only`：
+
+```bash
+backup="/tmp/sport-era-playwright-$(date +%Y%m%d%H%M%S)"
+mv .playwright-mcp "$backup"
+git pull --ff-only
+```
+
+工作区存在历史改动时，可只同步指定运行文件，避免覆盖其它现场文件：
+
+```bash
+git fetch origin dev.1.0.0
+git checkout -f origin/dev.1.0.0 -- docker/docker-compose.dev.yml docker/docker-compose.crawler.yml docker/crawler
+```
+
+### Compose 操作
+
+```bash
+cd /www/wwwroot/test-server.sbnews.net/docker
+
+# 检查配置，不启动服务
+sudo docker compose -f docker-compose.dev.yml config -q
+sudo docker compose -f docker-compose.crawler.yml config -q
+
+# PHP/前端/开发 crawler 环境
+sudo docker compose -f docker-compose.dev.yml ps
+sudo docker compose -f docker-compose.dev.yml build crawler
+sudo docker compose -f docker-compose.dev.yml up -d --no-build --force-recreate --no-deps crawler
+
+# 知识库 worker：依赖、Dockerfile 或 kb_worker.py 变化后必须重建
+sudo docker compose -f docker-compose.crawler.yml build kb-worker
+sudo docker compose -f docker-compose.crawler.yml up -d --no-build --force-recreate --no-deps kb-worker
+sudo docker compose -f docker-compose.crawler.yml ps kb-worker
+sudo docker logs --tail 100 sport-era-kb-worker
+```
+
+### 当前容器职责
+
+| 容器/服务 | 作用 | 网络与端口 |
+| --- | --- | --- |
+| `sport-era-dev-server-1` | PHP ThinkPHP API | host network，Docker Nginx 对外 `8000` |
+| `sport-era-dev-scheduler-1` | 每分钟执行 `php think crontab` | host network |
+| `sport-era-crawler` | Python 爬虫与容器 cron | host network，共用 crawler `logs/data` |
+| `sport-era-kb-worker` | 消费 Redis Stream，生成 Embedding，写入 AI 知识库 | host network，Redis Stream `ai:kb:sync:stream` |
+| `sport-era-dev-nginx-1` | Docker 内 Nginx/PHP-FPM 反代 | host network，监听 `8000` |
+| `sport-era-dev-admin-1` | Admin Vite 开发服务器 | `5176` |
+| `sport-era-dev-uniapp-h5-1` | uni-app H5 Vite 开发服务器 | `5177` |
+
+当前 Compose 不启动 MySQL/Redis 容器，使用测试服外部 MySQL `3300` 和 Redis `6377`；私有连接参数只放在 `docker/.env.server`、`docker/.env.docker`。
+
+### 宿主机 Nginx 与访问验证
+
+修改三个测试域名反代后执行：
+
+```bash
+sudo nginx -t
+sudo systemctl reload nginx
+
+curl -kI https://test-admin.sbnews.net/
+curl -kI https://testh5.sbnews.net/
+curl -kI https://test-server.sbnews.net/api/index/config
+```
+
+域名映射为：Admin → `5176`，H5 → `5177`，Server/API → `8000`。Admin/H5 当前是 Vite 开发模式，首屏慢时优先检查 Vite 模块转换；需要稳定快速访问时改用生产构建并由 Nginx 托管静态资源。
+
 ## 设计稿映射
 
 设计稿与页面/组件映射统一维护在：