开发环境

目的

定义一套新人可复现、CI 可验证的开发环境。开发环境不是“每个人自己配”，而是工程操作系统的底层服务之一。后续如果接入 Agent，也应复用同一套可复现环境。

新人需要直接运行项目时，先看 43-本地开发-local-development.md。本文件定义原则和要求，24 文档给可执行步骤。

参考仓库默认

这是一组 JS/TS + Go 的参考实现，不是通用硬要求。

能力 参考工具 需要说明清楚的内容
包管理 pnpm@9.15.0 安装依赖、锁文件策略、离线/CI 安装方式
Monorepo 编排 Turborepo 哪些任务被缓存，哪些任务必须每次真实执行
API / Web TypeScript / Node dev server、build、typecheck、test 命令
Runtime daemon Go claim/run loop 的启动、测试、构建命令
数据库 Postgres 16 本地启动、migration、seed、reset 方法
本地服务 Docker Compose 启动哪些依赖，端口和数据卷如何管理
环境变量 .env.example、.env.local 变量用途、是否 secret、默认值、缺失时表现
诊断 pnpm doctor 检查语言版本、依赖服务、环境变量、数据库连接

JS/TS + Go 参考启动流程

pnpm install
cp .env.example .env.local
pnpm doctor
docker compose up -d postgres
pnpm db:migrate
pnpm dev

如果要跑完整容器化环境：

docker compose up --build

其他语言应提供等价流程：

技术栈 依赖安装 启动依赖 Migration 启动应用 本地检查
JS/TS pnpm install --frozen-lockfile docker compose up -d postgres pnpm db:migrate pnpm dev pnpm check
Go go mod download docker compose up -d postgres 项目 migration CLI go run ./cmd/server go test ./...
Python uv sync 或 pip install -r requirements.txt docker compose up -d postgres alembic upgrade head 或 Django migrate uvicorn app:app --reload pytest、ruff check .
Rust cargo fetch docker compose up -d postgres sqlx migrate run 或 Diesel migration cargo run cargo test、cargo clippy

必须维护的本地能力

能力 要求
一键诊断 检查语言版本、包管理器、Docker、数据库连接、必要环境变量；JS/TS 示例是 pnpm doctor
一键启动 能启动本地 Web/API/worker 和依赖服务；JS/TS 示例是 pnpm dev + Docker Compose
一键检查 能跑合并前必要门禁；JS/TS 示例是 pnpm check，Go 示例是 go test ./...，Rust 示例是 cargo test
数据库迁移 migration 可重复执行，并能在空库或测试库中验证；JS/TS 示例是 pnpm db:migrate
Runtime 调试 能本地启动真实 daemon、fake daemon，并跑 runtime 协议测试；JS/TS 示例是 pnpm runtime:daemon、pnpm runtime:fake、pnpm runtime:test
Smoke 验证核心闭环，不只验证服务能启动；JS/TS 示例是 pnpm smoke:m1

这些能力必须写进当前项目的 docs/PROJECT.md。不要只写在组织级文档里，否则新人仍然不知道当前项目实际用哪个命令。

三角色开发环境责任

角色 负责什么 不合格表现
技术负责人 要求项目必须可复现、CI 必须可信 只有老员工能跑起来
产品负责人 确认 preview/staging 能支持产品验收 产品只能等上线后才看效果
平台 / 资深工程师 维护安装、启动、检查、排障命令 命令过期、环境变量靠私聊

新人环境验收

新人第一次加入项目时，应能按项目文档完成一次环境验收：

安装依赖
-> 启动依赖服务
-> 启动应用
-> 跑本地快速检查
-> 跑一个核心 smoke

验收结果应该记录在任务、入职 checklist 或项目文档修复 PR 中：

本地启动：成功 / 失败
检查命令：通过 / 失败
核心 smoke：通过 / 失败
文档缺口：

如果新人需要靠私聊才能跑起来，说明 docs/PROJECT.md 或 .env.example 不合格，应补文档。

环境变量规范

文件 用途
.env.example 所有变量的公开模板，不含真实 secret
.env.local 本地开发变量，不提交
CI env GitHub Actions 环境变量和 secrets
Runtime config runtime daemon 专用配置，不混入 Web/API

规则：

  1. 新增环境变量必须同步更新 .env.example。
  2. Secret 不得写进 .env.example、文档、截图或 Lark。
  3. 诊断命令应检查关键变量是否缺失；JS/TS 示例是 pnpm doctor。
  4. 后续 Agent 运行时只能拿到该 run 需要的最小变量。

开发环境服务清单

服务 本地来源示例 生产对应
Postgres Docker Compose Managed Postgres
API pnpm dev、go run、uvicorn、Docker API service
Web pnpm dev、framework dev server、Docker Web deployment
Runtime daemon Go/Rust/Node command 或 Docker Runtime worker
GitHub App mock/smoke fake server、recorded fixture、smoke script GitHub App
Provider smoke provider smoke command，例如 pnpm smoke:codex Provider integration

后续 Agent 就绪要求

这一节在人类开发环境已经可复现后再看。

Agent 可以执行任务前，开发环境必须能做到：

  1. 在干净 checkout 中安装依赖。
  2. 可创建隔离 worktree。
  3. 可运行迁移和测试。
  4. 可通过受控环境变量启动。
  5. 可记录执行日志和 artifact。
  6. 不依赖开发者个人 shell、个人 token 或隐藏本地配置。

下一步阅读

读完或填完这份文档后，通常继续看：