这个项目可以帮你在 Mac 上快速准备一个统一的 AI 开发环境。第一次安装好之后，你只需要在自己的项目目录里运行一条命令，就能进入已经准备好的开发环境。
这个环境里已经包含常用工具：
- Python
- Node.js
- pnpm
- uv
- git
- GitHub CLI
- Redis
- Qdrant
你不需要先理解 Docker、镜像、网络或数据卷。先按下面步骤跑起来即可。
这个工具适合：
- 想快速开始 AI Agent 项目的人
- 不想手动配置 Python、Node.js、Redis、Qdrant 的人
- 希望多个项目都使用同一套开发环境的人
- 希望环境可以启动、停止、清理，并且行为一致的人
你需要先安装：
- Docker Desktop 或 Colima
- mise
推荐把这个项目放到 ~/.ai-harness，这样以后可以在任意项目目录使用。
git clone <repo-url> ~/.ai-harness
cd ~/.ai-harness./scripts/check-host如果缺少组件，命令会提示安装方法。
./scripts/install-global安装完成后，你会得到一组 harness-* 命令。以后不需要每次进入 ~/.ai-harness 目录。
第一次使用前，建议先运行环境检查与测速：
mise run harness-check该命令会对你的宿主机进行画像并自动为国内用户配置镜像源加速。接着构建环境：
mise run harness-build第一次构建可能需要几分钟。以后通常不需要重复构建。
例如：
cd ~/projects/my-ai-agent如果项目目录还不存在：
mkdir -p ~/projects/my-ai-agent
cd ~/projects/my-ai-agentmise run harness-up成功后，你会进入一个命令行环境。你的当前项目目录会出现在这个环境里的 /workspace。
开发环境默认把容器内 8000-8099 端口发布到 Mac 本机的 127.0.0.1:8000-8099。
如果你在容器里启动 Web 服务，请让应用监听 0.0.0.0，并优先使用 8000-8099 之间的端口。例如：
python -m http.server 8000 --bind 0.0.0.0然后在 Mac 浏览器打开：
http://localhost:8000
如果你的 Docker 运行时可以稳定承载更大的端口窗口，也可以在启动前设置 HARNESS_PORT_RANGE=8000-9999。
日常使用只需要这几步：
cd 你的项目目录
mise run harness-up退出当前开发环境：
exit停止后台服务：
mise run harness-down| 我想要 | 运行命令 |
|---|---|
| 检查本机环境是否可用 | mise run harness-check |
| 第一次构建开发环境 | mise run harness-build |
| 启动并进入开发环境 | mise run harness-up |
| 快速进入开发环境 | mise run harness-shell |
| 在开发环境里运行一次命令 | mise run harness-run -- python --version |
| 查看工具版本 | mise run harness-versions |
| 查看 Redis 和 Qdrant 日志 | mise run harness-logs |
| 查看项目里的 Agent 日志 | mise run harness-agent-logs |
| 停止后台服务，保留数据 | mise run harness-down |
| 彻底清理环境和数据 | mise run harness-clean |
注意：harness-clean 会删除数据和本地镜像。普通停止请优先使用 harness-down。
进入环境后，可以运行：
python --version
node --version
pnpm --version
uv --version
git --version
gh --version如果这些命令都能输出版本号，说明开发工具已经可用。
也可以运行：
pwd
ls如果 pwd 显示 /workspace，并且 ls 能看到你项目目录里的文件，说明项目目录已经正确进入开发环境。
你的文件仍然保存在 Mac 原来的项目目录里。
当你运行：
cd ~/projects/my-ai-agent
mise run harness-up工具会把这个目录带入开发环境。在开发环境里，它显示为：
/workspace
你在 /workspace 里创建或修改的文件，会同步出现在 Mac 上的 ~/projects/my-ai-agent。
如果你的项目需要 OpenAI、Anthropic、Google 或其他服务的 API Key，请先把 Key 放到当前终端环境中。例如：
export OPENAI_API_KEY="你的 Key"启动环境时，工具会把当前终端里常见 AI 服务的 API Key 带入开发环境。
如果你是在本仓库目录开发这个工具本身，也可以复制模板文件：
cp .env.example .env| 命令 | 作用 | 是否删除数据 |
|---|---|---|
exit |
退出当前开发环境 | 否 |
mise run harness-down |
停止后台服务，保留数据 | 否 |
mise run harness-clean |
彻底清理容器、镜像、网络和数据 | 是 |
日常使用推荐：
mise run harness-down只有在你想完全重来，或者需要释放更多本地资源时，再使用：
mise run harness-clean如果你是在维护这个 Harness 项目本身，而不是在普通业务项目里使用它，可以在本仓库目录运行：
./scripts/check-host
docker build -t ai-dev:latest -f docker/Dockerfile .
./scripts/task-harness-up这些脚本是本仓库的本地开发入口。普通使用者更推荐先运行 ./scripts/install-global，再使用全局命令：
mise run harness-up这通常表示 Docker 已安装，但还没有启动。
如果你使用 Docker Desktop：
open -a Docker
docker version如果你使用 Colima：
colima start --runtime docker --cpu 4 --memory 8
docker version说明全局命令还没有安装，或 mise 没有加载配置。
先确认安装过：
~/.ai-harness/scripts/install-global再确认配置文件存在：
ls ~/.config/mise/config.toml先构建环境：
mise run harness-build也可以直接运行：
mise run harness-up如果镜像不存在，启动脚本会尝试自动构建。
Colima 默认更适合挂载 $HOME 下面的目录。建议把项目放在：
~/projects
避免放在 /tmp 等目录。
如果只是停止后台服务：
mise run harness-down如果想彻底清理并重新构建：
mise run harness-clean
mise run harness-build普通使用者通常只需要阅读本 README。
如果你需要排查问题、理解清理策略或查看日志，请看：
如果你需要了解底层实现、Docker 镜像、权限、挂载、网络和脚本设计，请看：