TashanGKD 测试环境自动准备（test-env-setup）
使命：让「说一句话就能开始测试」成为现实。 在测试智能体开始执行任何测试用例之前，自动完成所有环境准备工作。 若环境不可修复，输出明确的人工干预指引，不静默失败。
知识导航表
| 层级 | 文档 | 用途 |
|---|---|---|
| D1 项目配置 | 项目群/[项目]/.cursor/test-config.md（若存在） |
项目专属配置：端口/账号/技术栈 |
| D2 技术架构 | 项目群/[项目]/2_技术架构/技术框架.md |
了解服务架构和启动方式 |
| D3 部署文档 | 项目群/[项目]/DEPLOY_ARCH.md |
生产/测试账号信息 |
激活后立即执行
Step 0 【读取项目配置】
先尝试读取 .cursor/test-config.md（项目专属配置）
IF 不存在：使用智能推断（见后文「自动推断逻辑」）
Step 1 【后端服务健康检查 + 自动启动】
1.1 检查服务是否在目标端口响应：
```bash
curl -s --max-time 3 http://localhost:[PORT]/health 2>/dev/null
```
IF 响应正常（含 "ok" 或 HTTP 200）：
→ 输出「✅ 后端服务正常（端口 [PORT]）」
→ 跳到 Step 2
IF 无响应：
1.2 检查是否有进程占用端口：
```bash
lsof -i :[PORT] 2>/dev/null | head -5
```
IF 有进程但未响应 → kill 并重启：
```bash
pkill -f "uvicorn.*[PORT]" 2>/dev/null || true
pkill -f "node.*[PORT]" 2>/dev/null || true
sleep 2
```
1.3 自动启动服务（根据技术栈）：
FastAPI/Python 项目：
```bash
cd [项目根目录]
# 激活虚拟环境（优先 .venv，其次 venv，其次系统 Python）
PYTHON=$([ -f .venv/bin/python ] && echo .venv/bin/python || \
[ -f venv/bin/python ] && echo venv/bin/python || \
echo python3)
# 后台启动，日志写入 /tmp/test-backend.log
nohup $PYTHON -m uvicorn backend.app.main:app \
--host 0.0.0.0 --port [PORT] --workers 1 \
> /tmp/test-backend.log 2>&1 &
echo "启动PID: $!"
```
Node.js/Next.js 项目：
```bash
cd [项目根目录]
nohup npm run dev > /tmp/test-frontend.log 2>&1 &
```
1.4 等待服务就绪（最多 30 秒）：
```bash
for i in $(seq 1 10); do
sleep 3
curl -s http://localhost:[PORT]/health && echo "✅ 服务就绪" && break
echo "等待中... ($i/10)"
done
```
IF 30 秒后仍无响应：
→ 读取启动日志诊断：cat /tmp/test-backend.log | tail -20
→ 输出错误信息和诊断建议
→ 停止，输出：「❌ 后端服务无法自动启动，需要人工检查」
→ 附上日志内容供人工排查
Step 2 【数据库连接验证】
```bash
# 通过服务健康端点间接验证 DB
curl -s http://localhost:[PORT]/config-check 2>/dev/null | python3 -c "
import sys, json
d = json.load(sys.stdin)
print('DB:', '✅' if d.get('db_configured') else '❌')
" 2>/dev/null || echo "config-check 端点不可用（跳过DB验证）"
```
IF DB 未连接（db_configured=false）：
→ 尝试启动数据库（如有 docker-compose）：
```bash
docker-compose -f docker-compose.dev.yml up -d postgres 2>/dev/null || true
sleep 5
```
→ 重新检查
IF 仍然无法连接 → 输出「❌ 数据库连接失败，需要人工检查」
Step 3 【测试账号验证 + 自动创建（完整 Persona 体系）】
需要创建以下 4 类测试人格账号（Personas）：
```python
# 测试 Persona 定义（从 test-config.md 读取，以下为默认值）
PERSONAS = [
# admin：管理员，生成邀请码
{"phone": "10000000001", "password": "admin2026",
"role": "admin", "handle": "test_admin", "display_name": "测试管理员"},
# rich：丰富认知库，Proxy 测试目标 + Owner 模式测试
{"phone": "19900000001", "password": "sim2026",
"role": "creator", "handle": "user_rich", "display_name": "认知丰富用户",
"seed_workspace": True, # 需要预装知识库
"visibility": "public_free"}, # 公开供 Proxy 测试
# empty：空 workspace，冷启动/新用户测试
{"phone": "19900000088", "password": "newuser2026",
"role": "creator", "handle": "user_empty", "display_name": "新用户"},
# visitor：访客，专门用于 Proxy 对话 / 消息系统测试
{"phone": "19900000099", "password": "visitor2026",
"role": "user", "handle": "user_visitor", "display_name": "访客测试者"},
]
```
验证并创建缺失账号：
```python
import requests, json
BASE_URL = "http://localhost:[PORT]"
def check_account(phone, password):
r = requests.post(f"{BASE_URL}/auth/login", json={"phone": phone, "password": password})
return r.status_code == 200, r.json() if r.status_code == 200 else None
# 先确保 admin 账号存在（用 SQL 直接创建，绕过邀请码）
admin_exists, _ = check_account("10000000001", "admin2026")
IF not admin_exists:
# 用终端执行 Python 脚本直接写 DB
python -c "
import sys; sys.path.insert(0, 'backend')
from core.db import get_db
from core.auth import create_user, hash_password, create_profile
with get_db() as db:
uid = create_user(db, '10000000001', hash_password('admin2026'))
create_profile(db, uid, role='admin', display_name='测试管理员')
print(f'Admin 创建成功: {uid}')
"
# 用 admin 账号生成邀请码并创建其他账号
_, admin_data = check_account("10000000001", "admin2026")
admin_token = admin_data["access_token"]
r = requests.post(f"{BASE_URL}/admin/invite-codes",
headers={"Authorization": f"Bearer {admin_token}"},
params={"count": 10, "expire_days": 365})
codes = r.json()["codes"]
code_idx = 0
for persona in PERSONAS[1:]: # 跳过 admin
exists, _ = check_account(persona["phone"], persona["password"])
if not exists:
r = requests.post(f"{BASE_URL}/auth/register", json={
"phone": persona["phone"],
"password": persona["password"],
"invite_code": codes[code_idx],
"display_name": persona["display_name"],
"handle": persona["handle"],
})
print(f"注册 {persona['handle']}: {r.status_code}")
code_idx += 1
Step 3.5 【预装知识库（seed_workspace 标记的账号）】
对标记了 seed_workspace=True 的账号（默认：user_rich），
将预制知识库内容复制到其 workspace：
```bash
# 检查 fixture 目录是否存在
FIXTURE_DIR="tests/fixtures/rich_workspace"
if [ ! -d "$FIXTURE_DIR" ]; then
echo "⚠️ Fixture 目录不存在，正在从模板创建..."
mkdir -p "$FIXTURE_DIR/sources"
mkdir -p "$FIXTURE_DIR/docs/L1/产品理论维度"
mkdir -p "$FIXTURE_DIR/docs/L2"
# 创建已知内容的 fixture 文档（用于精确断言）
cat > "$FIXTURE_DIR/sources/认知杠杆论.md" << 'EOF'
# 认知杠杆论
AI时代的核心竞争力是认知结构而非执行效率。
知识管理的本质是建立连接，而非存储。
个人认知结构的稀缺性，决定了它在AI时代的价值。
EOF
cat > "$FIXTURE_DIR/sources/研究方法论.md" << 'EOF'
# 自下而上的系统性研究方法
从具体案例出发，逐步归纳规律，最后升维到原则。
避免一开始就构造大框架的陷阱。
EOF
echo "✅ Fixture 内容已创建"
fi
```
将 fixture 触发 build-cognition（让 AI 真正处理并建立认知结构）：
```python
import requests, time
# 登录 rich 账号
_, rich_data = check_account("19900000001", "sim2026")
rich_token = rich_data["access_token"]
rich_ws = rich_data["workspace_id"]
rich_headers = {"Authorization": f"Bearer {rich_token}"}
# 检查是否已有认知内容（避免重复 seed）
r = requests.get(f"{BASE_URL}/doc-registry", headers=rich_headers)
existing_docs = r.json().get("docs", [])
if len(existing_docs) < 3: # 少于3个文档，说明需要 seed
# 上传 fixture 文件
import os
from pathlib import Path
fixture_files = list(Path("tests/fixtures/rich_workspace/sources").glob("*.md"))
files = [("files", (f.name, open(f, "rb"), "text/markdown")) for f in fixture_files]
r = requests.post(f"{BASE_URL}/twin/upload", headers=rich_headers, files=files)
print(f"上传 fixture 文件: {r.status_code}, 文件数: {r.json().get('file_count')}")
# 触发认知构建（通过 SSE 等待完成）
print("⏳ 触发认知构建，等待完成（最多3分钟）...")
with requests.post(f"{BASE_URL}/twin/build-cognition",
headers=rich_headers, stream=True, timeout=180) as r:
for line in r.iter_lines():
if b'"done"' in line or b'build_done' in line:
print("✅ 认知构建完成")
break
else:
print(f"✅ rich 账号已有 {len(existing_docs)} 个文档，跳过 seed")
# 设置 rich 账号的分身为公开（供 Proxy 测试）
requests.post(f"{BASE_URL}/brain-square/visibility",
headers=rich_headers,
json={"visibility": "public_free"})
print("✅ rich 账号设为公开（供 Proxy 测试）")
```
Step 4 【Python 依赖验证】
```bash
cd [项目根目录]
# 验证关键依赖是否安装
$PYTHON -c "import requests, pytest, sseclient" 2>/dev/null && \
echo "✅ Python 依赖齐全" || \
(echo "⚠️ 安装缺失依赖..." && pip install requests pytest sseclient-py 2>&1 | tail -5)
```
Step 5 【最终就绪确认 + 输出报告】
```bash
# 最终健康检查
HEALTH=$(curl -s http://localhost:[PORT]/health 2>/dev/null)
echo "服务状态: $HEALTH"
# 验证两个测试账号均可登录
TOKEN_MAIN=$(curl -s -X POST http://localhost:[PORT]/auth/login \
-H "Content-Type: application/json" \
-d '{"phone":"[TEST_PHONE_MAIN]","password":"[TEST_PASSWORD_MAIN]"}' \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('access_token','FAIL')[:20])")
echo "主账号 Token: $TOKEN_MAIN"
```
输出就绪报告：
「✅ 测试环境就绪
服务状态：✅ localhost:[PORT]/health → ok
数据库：✅ 已连接
主测试账号（[TEST_PHONE_MAIN]）：✅ 可登录
新用户账号（[TEST_PHONE_NEW]）：✅ 可登录
Python 依赖：✅ 齐全
准备就绪，可以开始测试。」
自动推断逻辑（无 test-config.md 时）
推断后端端口：
grep -r "port.*810[0-9]\|:810[0-9]" [项目目录]/backend/ 2>/dev/null | head -3
→ 默认端口尝试顺序：8100 → 8000 → 3000
推断技术栈：
IF exists requirements.txt AND exists backend/ → FastAPI/Python
IF exists package.json AND exists pages/ → Next.js
IF exists package.json AND exists src/ → React/Node
推断数据库：
grep DATABASE_URL [项目目录]/.env 2>/dev/null
项目配置文件规范（.cursor/test-config.md）
# 测试环境配置
## 服务
BACKEND_PORT: 8100
HEALTH_ENDPOINT: /health
STARTUP_CMD: python -m uvicorn backend.app.main:app --port 8100 --workers 1
## 测试账号
TEST_PHONE_MAIN: 19900000001
TEST_PASSWORD_MAIN: sim2026
TEST_PHONE_NEW: 19900000088
TEST_PASSWORD_NEW: newuser2026
## 技术栈
LANGUAGE: python
TEST_CMD: python -m pytest tests/ -x -v --timeout=120
VENV_PATH: .venv
## P2 处理
P2_HANDLING: skip # skip / fix_all / ask
日志驱动断言工具（测试必用）
产品天然对 AI 透明：
/logs端点暴露所有工具调用、节点状态、SSE 事件。 用这些做断言，比「检查 AI 回答了什么文字」可靠 10 倍。
import requests
BASE_URL = "http://localhost:[PORT]"
def get_session_logs(headers, session_id=None):
"""获取当前 session 的完整操作日志"""
r = requests.get(f"{BASE_URL}/logs", headers=headers)
logs = r.json() if r.status_code == 200 else []
if session_id:
logs = [l for l in logs if l.get("session_id") == session_id]
return logs
def clear_logs(headers):
"""清空日志（每条 Layer 1 测试前调用，防止干扰）"""
requests.delete(f"{BASE_URL}/logs", headers=headers)
def assert_tool_called(logs, tool_name, args_contains=None):
"""验证某个工具被调用（不管 AI 输出了什么）"""
for log in logs:
if log.get("tool") == tool_name or tool_name in str(log.get("action", "")):
if args_contains is None:
return True
if args_contains in str(log.get("args", "")):
return True
return False
def assert_workflow_completed(events):
"""验证工作流完整执行完毕"""
event_types = [e.get("type") for e in events if isinstance(e, dict)]
return "workflow_done" in event_types
def assert_proposal_created(workspace_path):
"""验证工作流真的创建了 Proposal（文件系统状态断言）"""
from pathlib import Path
proposals = list(Path(workspace_path) / "proposals").glob("p-*.json"))
return len(proposals) > 0
def assert_doc_modified(workspace_path, doc_pattern, after_timestamp):
"""验证某文档在测试操作后被修改"""
from pathlib import Path
import os
for doc in Path(workspace_path).rglob(doc_pattern):
if os.path.getmtime(doc) > after_timestamp:
return True
return False
def count_l2_fragments(workspace_path):
"""统计 L2 碎片数量（认知积累断言）"""
from pathlib import Path
return len(list((Path(workspace_path) / "docs/L2").glob("*.md")))
断言优先级
1. 文件系统状态（最可靠）：Proposal 出现了吗？L2 有新文件吗？
2. 日志工具调用：read_skill 被调用了吗？write_file 被调用了吗？
3. SSE 事件序列：workflow_done 在所有 node_update 之后吗？
4. 接口响应结构：返回了正确的字段吗？
5. 文字内容（最后手段）：仅在格式强制要求时（如第三人称检查）
失败处理（人工干预指引）
| 情况 | 自动尝试 | 无法自动处理时的指引 |
|---|---|---|
| 后端服务无法启动 | kill+restart × 3 | 「查看 /tmp/test-backend.log，检查端口冲突或环境变量」 |
| 数据库无法连接 | 尝试 docker-compose up | 「检查 .env 的 DATABASE_URL，确认 PostgreSQL 在运行」 |
| 测试账号无法创建 | 尝试管理员 API 创建 | 输出手动创建 SQL |
| 依赖缺失 | pip install | 「运行 pip install -r requirements.txt」 |
变更记录
v1.0 — 2026-03-24 — 初始创建
根因：Agent 拥有完整终端权限，但之前测试流程的「第一步」仍是人工确认环境就绪。 需要一个专门的 Skill 把环境准备工作完全自动化，让「说一句话就能开始测试」成为现实。
设计决策：
- 5步串行（健康检查→DB→账号→依赖→就绪确认）
- 每步有自动修复逻辑，修复3次失败才报告人工干预
- 支持 .cursor/test-config.md 项目配置，无配置时智能推断
- 输出就绪报告，让调用方知道环境状态
验证状态：🔵 待验证