{"record":{"id":"0562af40d9184a91","repo":"datawhalechina/hello-agents","slug":"agents-md","errorCode":null,"errorMessage":"AGENTS.md 配置文件不存在，请检查工作空间初始化","messagePattern":"AGENTS\\.md 配置文件不存在，请检查工作空间初始化","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Co-creation-projects/tino-chen-HelloClaw/src/agent/helloclaw_agent.py","lineNumber":201,"sourceCode":"            if hasattr(self, '_agent'):\n                self._agent.llm = self._llm\n\n            return True\n        return False\n\n    def _build_system_prompt(self) -> str:\n        \"\"\"构建系统提示词\n\n        从 AGENTS.md 读取主要内容，附加其他配置文件作为上下文。\n        如果入职未完成，注入 BOOTSTRAP.md 引导内容。\n\n        Raises:\n            RuntimeError: 如果 AGENTS.md 不存在\n        \"\"\"\n        # 从 AGENTS.md 读取（必须存在）\n        agents_content = self.workspace.load_config(\"AGENTS\")\n        if not agents_content:\n            raise RuntimeError(\"AGENTS.md 配置文件不存在，请检查工作空间初始化\")\n\n        base_prompt = agents_content\n\n        # 加载其他配置文件作为上下文\n        context_parts = []\n\n        # 检查入职是否完成\n        if not self.workspace.is_onboarding_completed():\n            bootstrap = self.workspace.load_config(\"BOOTSTRAP\")\n            if bootstrap:\n                context_parts.append(f\"\\n## 初始化引导\\n\\n{bootstrap}\")\n\n        # 身份信息\n        identity = self.workspace.load_config(\"IDENTITY\")\n        if identity:\n            context_parts.append(f\"\\n## 你的身份信息\\n{identity}\")\n\n        # 用户信息","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/tino-chen-HelloClaw/src/agent/helloclaw_agent.py#L183-L219","documentation":"HelloClawAgent._build_system_prompt calls workspace.load_config(\"AGENTS\") and raises RuntimeError when it returns falsy. AGENTS.md is the mandatory core of the agent's system prompt (other configs like BOOTSTRAP are optional add-ons), so its absence means the workspace was never initialized through the intended onboarding/setup flow. This fails at prompt-build time, i.e. on the first conversation turn, not at agent construction.","triggerScenarios":"Starting HelloClawAgent against a fresh/empty workspace directory where init (which writes AGENTS.md) was skipped; workspace path misconfigured so load_config reads the wrong directory; AGENTS.md deleted or renamed (agents.MD, agents.md casing on a case-sensitive FS); a previous init run failed halfway leaving other configs present but AGENTS.md missing.","commonSituations":"New clone used immediately without the workspace-init command; running on Linux after creating the file as AGENTS.md on macOS/Windows then copying with wrong case; init crash (permissions, disk) after creating the directory but before writing AGENTS.md; tests pointing at a temp workspace with no fixtures.","solutions":["Run the workspace initialization/onboarding step provided by HelloClaw (the one that writes AGENTS.md) before starting the agent.","If init already ran, check the workspace path the agent was constructed with and list its files to confirm AGENTS.md exists with exact casing.","Create a minimal AGENTS.md manually (project overview + coding conventions) to unblock, then complete onboarding.","Re-run init after fixing the underlying write failure (permissions, disk space).","Add a startup assertion: fail at construction, not first turn, when AGENTS.md is missing."],"exampleFix":"# before\nagent = HelloClawAgent(name=\"claw\", workspace=WorkspaceManager(\"./ws\"))\nagent.run(\"hi\")  # RuntimeError at prompt build\n# after\nws = WorkspaceManager(\"./ws\")\nif not ws.load_config(\"AGENTS\"):\n    ws.init_workspace()  # or: raise SystemExit(\"workspace not initialized — run init first\")\nagent = HelloClawAgent(name=\"claw\", workspace=ws)\nagent.run(\"hi\")","handlingStrategy":"validation","validationCode":"ws = WorkspaceManager(workspace_path)\nif not ws.load_config(\"AGENTS\"):\n    raise SystemExit(\n        f\"workspace at {workspace_path} is not initialized — \"\n        \"run the HelloClaw init/onboarding step (creates AGENTS.md) first\"\n    )","typeGuard":"def workspace_is_ready(ws) -> bool:\n    return bool(ws.load_config(\"AGENTS\"))","tryCatchPattern":"try:\n    agent.run(user_msg)\nexcept RuntimeError as e:\n    if \"AGENTS.md\" in str(e):\n        raise SystemExit(\"workspace not initialized — run init before chatting\") from e\n    raise","preventionTips":["Run workspace init as part of first-run bootstrap, verified in CI","Check AGENTS.md existence at agent construction, not first turn","On case-sensitive filesystems use exact casing AGENTS.md"],"tags":["initialization","workspace","configuration","python","runtime-error"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}