Agentswarm/PROJECT_STANDARD.md

PROJECT_STANDARD.md — HeiCode Swarm 工程标准

本文件约定本仓（agent_swarm_v5 / HeiCode-Swarm）的工程标准。与 heicodeDocs 冲突时，以 heicodeDocs 为准；本文件仅作本仓落地补充。配套：CLAUDE.md、README.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 / 计费 / 密钥 / 审计 / 发布链路 / 文档）。
• 提交信息清晰描述改动；保持与现有代码风格一致。