# 配置与运行快速指引

> 针对第一次接手仓库或需要快速起盘的新同学，提供最小可行环境与常见操作。详细参数说明请参阅 `docs/CONFIG_REFERENCE.md`。

## 1. 环境准备
1. 安装 Node.js ≥ 22、pnpm ≥ 8。
2. 复制 `.env.example` → `.env`，填写 Pacifica 凭证（maker/hedger API key、私钥、可选子账户）。  
   - 若仅使用单账户，本地可临时填写 `PACIFICA_ACCOUNT_ADDRESS` / `PACIFICA_ACCOUNT_PRIVATE_KEY`，Runner 会自动映射到 `maker`。
3. `pnpm install` 安装依赖，确认 `pnpm lint` / `pnpm test` / `pnpm typecheck` 可通过。

## 2. 创建策略配置
```bash
cp config/config.example.yaml config/config.yaml
```
- 修改 `accounts` 段落，确保每个账户拥有唯一 `id` / `role`。  
- `grid` → `symbol`, `grid_step_bps`, `grid_range_bps`, `max_layers` 等按目标市场调整。  
- 如需多网格实例，暂沿用单实例配置；M1.6 之后会提供 `grid.instances[]`。  
- 其余参数可保持默认，详细释义参考 `CONFIG_REFERENCE.md`。

## 3. 启动 / 停止
```bash
# 实盘 Runner（默认读取 config/config.yaml）
pnpm run live

# Dry-run / 日志观察（以 --paper 启动）
pnpm run live -- --paper

# 优雅停止
curl -X POST http://localhost:4000/api/halt -d '{"reason":"maintenance"}'
```
- Runner 会在控制台输出日志文件路径 `logs/runner-<timestamp>.log`，便于后续排查。  
- 热更新：修改配置后执行 `curl -X POST http://localhost:4000/api/config/reload`，观察金丝雀指标 10 分钟。

## 4. 常见检查
- `pnpm lint` / `pnpm test` / `pnpm typecheck`：保证提交质量。  
- `pnpm run status`（可选脚本）或查看 `logs/runner-*.log` 中的 `Grid status`、`orderRouter` 指标。  
- Prometheus/Grafana 面板配置参见 `docs/OPERATIONS_PLAYBOOK.md`。

## 5. 推荐的阅读顺序
| 场景 | 推荐文档 |
|------|---------|
| 了解整体架构 | `ARCHITECTURE_DESIGN.md`, `SEQUENCE_FLOW.md` |
| 查看迭代计划 | `IMPLEMENTATION_PLAN.md`, `M16_*.md` 系列 |
| 调参 / 验证 | `CONFIG_REFERENCE.md`, `TESTING_PLAN.md` |
| 运维 / 降级 | `OPERATIONS_PLAYBOOK.md` |

> 历史方案与早期文档已迁移至 `docs/archive/`。如需回溯 v1.0 微网格设计、PRD 等资料，请查看该目录。
