> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 环境设置

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">需要帮助？</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>在 Discord 提问</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>提交 GitHub Issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/zh-Hans/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>支持指南</span>
    </a>
  </div>
</div>

这个共享设置指南适用于面向公众的入门项目，这些项目在实践者、构建者和贡献者路径中被引用。

## 这个设置的用途

* 在本地阅读 Agent Systems Handbook
* 运行当前仓库维护的入门代码
* 在贡献工作之前或之后验证示例项目

当前的示例项目刻意保持为轻量级的 Python 入门项目。它们足够小，可以快速检查，并且无需特定框架的工具链即可验证。

## 先决条件

* Git
* Python 3.9 或更新版本
* macOS、Linux 或 WSL 上的终端

## 克隆仓库

```bash theme={null}
git clone https://github.com/Prompthon-IO/agent-systems-handbook.git
cd agent-systems-handbook
```

## 可选的虚拟环境

当前的入门检查只使用 Python 标准库，但隔离环境仍然是一个很好的默认选择：

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
python3 --version
```

## 验证当前入门代码

运行仓库级别的烟雾测试检查：

```bash theme={null}
python3 scripts/verify_example_projects.py
```

这会验证以下位置下的当前入门代码：

* `patterns/examples/`
* `systems/examples/`
* `ecosystem/examples/`
* `case-studies/examples/`

## 可选的文件名大小写 Git hook

如果你在 Windows、macOS 或其他大小写不敏感的文件系统上贡献，请在 push
之前安装共享 Git hooks：

```bash theme={null}
git config core.hooksPath githooks
```

当前的 `pre-push` hook 会运行：

```bash theme={null}
python3 scripts/check_filename_casing.py
```

这会在 push 到达 CI 或 Linux review 环境之前，捕捉只在大小写上不同的路径冲突，
以及受追踪路径的大小写漂移。

## 预期结果

* 该检查会验证当前的代码草图和示例流程。
* 当前项目仍被文档化为 `starter` 示例，而不是完整的生产应用程序。
* 一些入门项目会演示状态形状或控制流，但尚未包含周边的传输、持久化或框架运行时。

## 如果你正在贡献

* 将示例项目保留在对应路径本地的 `examples/` 文件夹中。
* 将项目状态声明为 `starter`、`partial` 或 `runnable`。
* 如果你更改了可执行的入门代码，请在同一次更改中更新 `scripts/verify_example_projects.py`。