fix:批量修复了一些问题

docs/04-agents.md

@@ -129,6 +129,19 @@ agents/
 迭代 prompt 时:复制 `h2h_v1.md` → `h2h_v2.md`,改内容,传 `prompt_version: "v2"`。
 `predictions.prompt_version` 存的是 `multi_v2`,与 single 模式的 `v1`/`v2` 天然分组,可在 eval summary 中 A/B 对比。
 
+### 版本纪律(强制)
+
+> **改 prompt 内容必须 bump 版本号(v2→v3),禁止默默修改 `*_v1.md` 内容却不改版本。**
+
+原因:
+1. **可复现性**:`predictions.prompt_version` 决定哪份 prompt 产生了历史预测;篡改 v1 会让历史预测的 prompt 来源失真,eval 对比失效。
+2. **A/B 可信度**:`get_eval_summary` 按 `(provider, model, prompt_version)` 分组。若 v1 内容在不同时间指向不同 prompt,则 v1 桶内数据不可比。
+3. **缓存一致性**:模板内容 hash 写入缓存键(`_prompt_template_hash`),版本不变则 hash 不变,命中旧缓存。bump 版本自动让旧缓存失效。
+
+**流程**:改 prompt → 新建 `*_v{N+1}.md` → 新请求传 `prompt_version=v{N+1}` → 旧版本文件保持不变(供历史复现)。
+
+代码保证:写入 DB 的 `prompt_version` 与 `_load_prompt_template(version)` / `load_agent_prompt(name, version)` 加载的文件**严格一致**,不会漂移。
+
 ## 如何新增一个专家 Agent
 
 三步:

docs/06-deployment.md

@@ -162,9 +162,60 @@ cat backup.sql | docker exec -i profeto-postgres psql -U football football
 
 ## 监控
 
-- `/health`: 存活检查
-- 日志:容器 stdout(`docker compose logs -f api`)
-- 评估汇总:`GET /api/v1/eval/summary`(准确率/RMSAE/校准度)
+### 健康检查
+
+| 端点 | 含义 | HTTP 状态码 |
+|---|---|---|
+| `/health` | 存活检查(liveness) | 始终 200(进程在跑即活) |
+| `/health/ready` | 就绪检查(readiness) | DB 可达 200,不可达 **503** |
+
+### 探针配置
+
+#### Docker Compose
+
+`docker-compose.yml` 已为 `api` 服务配置 readiness:
+
+```yaml
+healthcheck:
+  test: ["CMD-SHELL", "curl -sf http://localhost:8000/health/ready || exit 1"]
+  interval: 10s
+  timeout: 5s
+  retries: 3
+  start_period: 10s
+```
+
+**要点**:必须指向 `/health/ready` 而非 `/health`——后者始终 200,在数据库故障时仍会接收流量,导致请求全部失败。
+
+#### Kubernetes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 8000
+  initialDelaySeconds: 5
+  periodSeconds: 15
+readinessProbe:
+  httpGet:
+    path: /health/ready
+    port: 8000
+  initialDelaySeconds: 10
+  periodSeconds: 10
+  failureThreshold: 3
+```
+
+**两探针必须区分**:
+- `livenessProbe` 用 `/health`:仅在进程死锁/崩溃时重启,避免误杀。
+- `readinessProbe` 用 `/health/ready`:DB 不可用时停止转发流量,恢复后自动切回。
+
+#### 验证
+
+```bash
+# 宿主机直接运行(经本地 8000 端口)
+python3 tests/test_health_ready.py
+```
+
+### 评估
 
 ## 安全与限流
 

docs/07-development.md

@@ -2,32 +2,70 @@
 
 ## 本地开发环境搭建
 
+### 锁定依赖策略
+
+项目使用 [pip-tools](https://github.com/jazzband/pip-tools) 锁定依赖版本,确保本地、CI、Docker 三端一致:
+
+| 文件 | 用途 | 生成命令 |
+|---|---|---|
+| `requirements.txt` | 生产依赖锁定(含 SHA256 哈希) | `pip-compile pyproject.toml --generate-hashes` |
+| `requirements-dev.txt` | 开发+CI 依赖锁定(含哈希) | `pip-compile pyproject.toml --extra dev --generate-hashes` |
+
+### 安装步骤
+
 ```bash
 # 1. 克隆并进入项目
 cd Profeto
 
-# 2. 安装依赖(含 dev)
-pip install -e ".[dev]"
+# 2. 创建虚拟环境
+python3.11 -m venv .venv
+source .venv/bin/activate
 
-# 3. 启动 PostgreSQL
+# 3. 安装 pip-tools(用于同步锁定依赖)
+pip install pip-tools
+
+# 4. 同步生产+开发依赖到当前环境(严格按 lock 文件版本,含哈希校验)
+pip-sync requirements-dev.txt
+
+# 5. 启动 PostgreSQL(或在 .env 配置外部库)
 docker run -d --name profeto-pg \
   -e POSTGRES_USER=football -e POSTGRES_PASSWORD=football -e POSTGRES_DB=football \
   -p 5432:5432 postgres:16-alpine
 
-# 4. 配置环境变量
+# 6. 配置环境变量
 cp .env.example .env
 # 编辑 .env 填 LLM_API_KEY / BZZOIRO_KEY
 
-# 5. 建表
+# 7. 建表
 alembic upgrade head
 
-# 6. 启动 API(热重载)
+# 8. 启动 API(热重载)
 uvicorn src.api.app:app --reload
 
-# 7. 启动前端(另一个终端)
+# 9. 启动前端(另一个终端)
 cd frontend && npm install && npm run dev
 ```
 
+> **注意**:不要用 `pip install -e ".[dev]"` 直接安装——它按 pyproject 下界约束解析,版本可能与 lock 文件不一致。统一用 `pip-sync requirements-dev.txt` 保证三端一致。
+
+### 变更依赖时
+
+```bash
+# 1. 编辑 pyproject.toml(调整依赖或版本约束)
+
+# 2. 重新生成 lock 文件(含哈希)
+pip-compile pyproject.toml --generate-hashes --output-file=requirements.txt --index-url=https://pypi.tuna.tsinghua.edu.cn/simple
+pip-compile pyproject.toml --extra dev --generate-hashes --output-file=requirements-dev.txt --index-url=https://pypi.tuna.tsinghua.edu.cn/simple
+
+# 3. 同步到本地环境
+pip-sync requirements-dev.txt
+
+# 4. 提交 lock 文件
+git add requirements.txt requirements-dev.txt pyproject.toml
+```
+
+> **禁止无故大升级主版本依赖**:仅升级真正需要的包,并重新跑全量测试。
+
 ## 项目结构
 
 ```