datawhalechina/hello-agents · error · FileNotFoundError

未找到项目目录，请从项目目录或仓库根目录启动 Notebook

Error message

未找到项目目录，请从项目目录或仓库根目录启动 Notebook

What it means

FileNotFoundError raised by the RequirementClarifierAgent notebook's bootstrap cell when none of the three candidate directories (cwd, cwd/Co-creation-projects/<project>, cwd.parent/<project>) contains main.py. The cell uses PROJECT_ROOT discovery so imports from src.* and .env loading work regardless of where Jupyter was started; if no candidate matches, it refuses to continue rather than importing the wrong package or silently skipping dotenv.

Source

Thrown at Co-creation-projects/zenith191-RequirementClarifierAgent/main.ipynb:55

    "from pathlib import Path\n",
    "\n",
    "from dotenv import load_dotenv\n",
    "from hello_agents import HelloAgentsLLM, SimpleAgent, ToolRegistry\n",
    "from hello_agents.tools import Tool, ToolParameter\n",
    "from IPython.display import Markdown, display\n",
    "\n",
    "project_name = \"zenith191-RequirementClarifierAgent\"\n",
    "candidates = [\n",
    "    Path.cwd(),\n",
    "    Path.cwd() / \"Co-creation-projects\" / project_name,\n",
    "    Path.cwd().parent / project_name,\n",
    "]\n",
    "PROJECT_ROOT = next(\n",
    "    (path.resolve() for path in candidates if (path / \"main.py\").exists()),\n",
    "    None,\n",
    ")\n",
    "if PROJECT_ROOT is None:\n",
    "    raise FileNotFoundError(\"未找到项目目录，请从项目目录或仓库根目录启动 Notebook\")\n",
    "if str(PROJECT_ROOT) not in sys.path:\n",
    "    sys.path.insert(0, str(PROJECT_ROOT))\n",
    "\n",
    "load_dotenv(PROJECT_ROOT / \".env\")\n",
    "\n",
    "from src.agents import build_agent_team\n",
    "from src.config import LLMSettings\n",
    "from src.tools import create_tool_registry\n",
    "from src.workflow import RequirementClarifierWorkflow\n",
    "\n",
    "print(f\"✅ 环境配置完成：{PROJECT_ROOT}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 第2部分：工具定义\n",

View on GitHub (pinned to 606a07d341)

Solutions

1. Start Jupyter from the repo root (so cwd/Co-creation-projects/zenith191-RequirementClarifierAgent resolves) or from the project directory itself, then re-run the cell.
2. Verify the project folder name matches 'zenith191-RequirementClarifierAgent' exactly and contains main.py; rename the folder or adjust project_name if it differs.
3. For headless runs (papermill/nbconvert), pass the correct working directory or add the absolute project path as an extra candidate in the list.
4. If main.py genuinely does not exist yet (early scaffold), create it or change the detection marker to a file that does exist (e.g. pyproject.toml).

Example fix

// before
candidates = [
    Path.cwd(),
    Path.cwd() / "Co-creation-projects" / project_name,
    Path.cwd().parent / project_name,
]
PROJECT_ROOT = next((p.resolve() for p in candidates if (p / "main.py").exists()), None)

// after (allow explicit override + richer marker)
candidates = [
    Path(os.environ.get("RCA_PROJECT_ROOT", "")) if os.environ.get("RCA_PROJECT_ROOT") else None,
    Path.cwd(),
    Path.cwd() / "Co-creation-projects" / project_name,
    Path.cwd().parent / project_name,
]
PROJECT_ROOT = next(
    (p.resolve() for p in candidates if p and (p / "main.py").exists()),
    None,
)

from pathlib import Path
import os

PROJECT_NAME = "zenith191-RequirementClarifierAgent"

def find_project_root() -> Path | None:
    override = os.environ.get("RCA_PROJECT_ROOT")
    candidates = [
        Path(override) if override else None,
        Path.cwd(),
        Path.cwd() / "Co-creation-projects" / PROJECT_NAME,
        Path.cwd().parent / PROJECT_NAME,
        Path(__file__).resolve().parent if "__file__" in globals() else None,
    ]
    return next((p.resolve() for p in candidates if p and (p / "main.py").exists()), None)

root = find_project_root()
if root is None:
    raise SystemExit(f"未找到 {PROJECT_NAME}：请从项目目录或仓库根目录启动，或设置 RCA_PROJECT_ROOT")

try:
    PROJECT_ROOT = next((p.resolve() for p in candidates if (p / "main.py").exists()), None)
    if PROJECT_ROOT is None:
        raise FileNotFoundError("未找到项目目录，请从项目目录或仓库根目录启动 Notebook")
except FileNotFoundError as e:
    print(f"{e} — 候选路径: {[str(c) for c in candidates]}")
    raise

When it happens

Trigger: Starting Jupyter from any directory that is not the project directory, the repo root, or a parent of the project (e.g. ~ or /tmp); the project was cloned/renamed so the folder is not literally 'zenith191-RequirementClarifierAgent'; main.py deleted or not yet created in a work-in-progress repo; symlinked paths where Path.cwd().parent resolution differs from expectation.

Common situations: Running the notebook through VS Code/JupyterLab opened at a random folder; running via nbconvert/papermill from an automation cwd; nested-clone layouts (repo inside another repo) making cwd.parent/<name> miss; case-sensitivity or trailing-space differences in the cloned directory name.

Related errors

• Chapter not found
• 会议记录过短，请至少提供 20 个字符
• 未找到 {env_path} 请执行: copy .env.example backend\.env 并填入 TMDB

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/0f74f9e4e74856b0. Report an issue: GitHub.