# PROJECT_STANDARD.md — HeiCode Swarm 工程标准

本文件约定本仓（`agent_swarm_v5` / HeiCode-Swarm）的工程标准。与 heicodeDocs 冲突时，以 **heicodeDocs** 为准；本文件仅作本仓落地补充。配套：[CLAUDE.md](CLAUDE.md)、[README.md](README.md)、[docs/DELIVERY.md](docs/DELIVERY.md)。

## 运行时与依赖
- Python 3.13+；依赖见 `orchestrator/requirements.txt`、`agent/requirements.txt`。
- 模型后端：**OpenAI 兼容** Chat Completions（`OPENAI_API_KEY` / `OPENAI_API_BASE` / `OPENAI_MODEL`，可指向自定义端点）。
- 持久化：**Redis 为权威存储**。`fakeredis` 内存回退仅限开发/CI，且必须由 `REDIS_FAKE` / `ALLOW_MEMORY_STORE` 显式开启；生产在 Redis 不可用时快速失败。

## 功能开关（默认关闭，保持契约）
- `ENABLE_PLANNER_FALLBACK`：无 Manager 分工时启用 LLM 规划回退。
- `ENABLE_REVIEW_LOOP` / `MAX_REVIEW_CYCLES`：主控评审/重做循环 + 结果汇总。
- `ENABLE_SUBTASK_HANDOFF`：动态子任务移交。
- 开启上述开关不得改变 Manager 面接口、回调、审批链与计费/审计字段语义。

## 安全
- 不得提交密钥/Token/凭据/`.env`/证书/私钥；通过环境 / `secret_ref` / Key Vault 注入。
- K8s 部署：Agent 模型密钥使用 Secret `openai-secret`（Pod 模板）或 `openai-api-key`（Deployment 清单）。
- 保留模型用量归属（`usage`、`X-Agent/X-Agnet` 头）以满足计费/审计。

## 测试与验收（PR 前必须通过）
```
python scripts/test-runtime-contract.py    # Manager 契约校验
python scripts/test-merge-smoke.py          # 机制级冒烟（评审/协作/汇总等）
python scripts/test-workflow-e2e.py         # 端到端工作流（无需密钥）
```
- 新增/修改逻辑应补充对应断言；不得以 TODO / mock 充当完成。
- 涉及 Manager 契约的改动，必须先通过 `test-runtime-contract.py`。

## 部署
- 正式部署走**镜像**：`Dockerfile.orchestrator` / `Dockerfile.agent` + `k8s/` 清单（`orchestrator-deployment.yaml` 使用 `swarm-orchestrator:latest`）。
- `k8s/orchestrator-source-configmap.yaml` 为陈旧快照，请勿用于当前部署（见 `docs/DELIVERY.md` §九）。

## 提交与分支
- 禁止直接 push / force push `main`；所有改动经 PR 合并，至少 1 人 review。
- PR 必须按 `.github/pull_request_template.md` 声明影响范围（Client / Manager / Agent-Swarm / CodeGW / 计费 / 密钥 / 审计 / 发布链路 / 文档）。
- 提交信息清晰描述改动；保持与现有代码风格一致。