一次配置，跑通两条轨道Set up once, run both tracks

Python 2.0.11

在工作区根目录使用独立虚拟环境。运行 lab.py 前先激活它，这样 CLI、测试与 Java 的 MCP 客户端会使用同一个解释器。Use a dedicated virtual environment at the workspace root. Activate it before running lab.py so the same interpreter is used by the CLI, tests and the Java MCP client.

cd E:/Agent开发相关/AgentScope学习
python -m venv .venv-lab
.venv-lab/Scripts/python -m pip install -r lab/requirements.txt
cd lab
../.venv-lab/Scripts/python.exe lab.py doctor

cd /path/to/AgentScope学习
python3 -m venv .venv-lab
.venv-lab/bin/python -m pip install -r lab/requirements.txt
cd lab
../.venv-lab/bin/python lab.py doctor

doctor 会打印 Python 版本、agentscope 版本、Java 与 Maven 路径，以及解析后的 lab 根目录。doctor prints the Python version, agentscope version, Java and Maven paths, and the resolved lab root.

Java 2.0.4

需要 JDK 17+ 与 Maven 3.9+。pom 会解析 agentscope-core、model-openai 与 rag-simple。只有在依赖已缓存到本地后才使用 -o。Requires JDK 17+ and Maven 3.9+. The pom pulls agentscope-core, model-openai and rag-simple. Use -o only after the dependencies are cached locally.

cd lab/java
mvn -q compile exec:java -Dexec.args="check p0"

cd lab/java
mvn -q -o compile exec:java -Dexec.args="check p0"

exec:java 不会自动重新编译。务必先 compile，否则旧 class 会掩盖你的修改。exec:java does not recompile automatically. Always run compile first, or a stale class can hide your edit.

常用命令Commands

cd lab
python lab.py list
python lab.py run m1
python lab.py check m1
python lab.py check --all

cd lab/java
mvn -q -o compile exec:java -Dexec.args="list"
mvn -q -o compile exec:java -Dexec.args="run m1"
mvn -q -o compile exec:java -Dexec.args="check m1"
mvn -q -o compile exec:java -Dexec.args="check --all"

任务阶梯Mission ladder

每次 check 会打印 PASS CODE、XP 与徽章名。在站点领取通行码即可记录到所选轨道。Each check prints PASS CODE, XP and the badge name. Claim the code on the site to record progress for the selected track.

排障Troubleshooting

• ModuleNotFoundError: agentscope —— 你用的是系统 Python。请用 .venv-lab 运行 lab.py。ModuleNotFoundError: agentscope — you are using the system Python. Run lab.py with .venv-lab.
• Maven 离线解析不到 agentscope-core —— 去掉一次 -o，或让 Maven 指向含有 2.0.4 的仓库。Maven cannot resolve agentscope-core offline — remove -o once, or point Maven at a repository that has 2.0.4.
• Java MCP 初始化超时 —— .venv-lab 必须安装 mcp，且 PYTHONPATH 要指向 lab 根目录。Java MCP init timeout — the .venv-lab interpreter must have mcp installed and PYTHONPATH must point at the lab root.
• Java RAG 检索为空 —— RetrieveConfig 默认 scoreThreshold 0.5，而哈希嵌入只有约 0.28，需要设为 0.0。RAG returns nothing in Java — RetrieveConfig defaults to scoreThreshold 0.5, while hash embeddings score around 0.28. Set 0.0.
• Tool not found —— Python 的 MCP 工具带 mcp__server__ 前缀，Java 直接用远端名。检查脚本里的工具名。Tool not found — Python MCP tools carry mcp__server__ prefixes, Java exposes the remote name. Check the scripted tool name.