Initial commit

2026-06-08 17:32:34 +08:00
commit d0fa193f79
91 changed files with 19645 additions and 0 deletions
@@ -0,0 +1,37 @@
+# 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 / 计费 / 密钥 / 审计 / 发布链路 / 文档）。
+- 提交信息清晰描述改动；保持与现有代码风格一致。