Files

T

gongzhiyongandOmX a4d771ede5 Define numeric swarm acceptance gates

Add a concrete 0-100 swarmness/compliance score, local large-scale stress, and 3000 TPM budget acceptance so the repo can say when it is a swarm by measured criteria instead of prose alone.

Constraint: user required Chinese docs, explicit scenarios, parameters, formulas, pass/fail lines, and git upload.

Rejected: prose-only PASS reports | they did not answer whether the system is a swarm with a concrete score.

Confidence: high

Scope-risk: moderate

Directive: keep production runtime claims separate from local minimal swarm acceptance scores.

Tested: py_compile swarm_minimal examples tests; unittest discover -s tests 45 tests; run_swarm_compliance_score.py; run_tpm_budget_acceptance.py; run_academic_standard_evaluation.py; git diff --check; docs/script secret-pattern scan.

Not-tested: live S07 and production Kubernetes/NewAPI provider-rate-limit stress were not rerun in this upload step.

Co-authored-by: OmX <omx@oh-my-codex.dev>

2026-05-17 18:19:24 +08:00

32 KiB

Raw Blame History

Agnet 受控蜂群设计原理

版本: v0.2
日期: 2026-05-15
状态: 设计原理与落地依据
适用范围: Heicode、Heicode Manager、Agnet 平台、Azure AKS、密钥保管器、CodeGW

当前仓库状态（2026-05-16）

本文是受控蜂群的目标架构与设计原则，不是只描述当前 fengqun 仓库的代码实现。当前仓库已经把设计中的最小闭环压缩成可测试原型，并完成以下验收：

Agent / 蜂群 Agent 质量标准采用 AQS / SW-AQS v1，不使用普通软件开发质量门替代 Agent 质量门。
标准矩阵已扩展为 S01-S10，包含 S07 外部 GitHub 复杂代码 live 场景、S09 下一阶段边界最小验收和 S10 蜂群六特征验收。
最小代码已覆盖任务池、共享状态、信息素、handoff、质量门、fallback、多轮质量共识、3/5/7 并发 claim、候选融合、互相质询，以及去中心化、自组织、涌现性、鲁棒性、可扩展性、隐式协作六个蜂群一级指标。

本文仍然保留完整平台设计边界：Heicode 客户端、Manager、Agnet 平台、Azure AKS、密钥保管器和 CodeGW 的生产级整合尚未由当前仓库完成。后续修改本文时，应继续区分“当前最小原型已验收”和“目标平台仍需落地”。

0. 核心修正

Agnet 蜂群不应该依托瀑布、敏捷、Scrum、Sprint 或传统项目管理框架。

这些方法论是为人类团队协作设计的，核心是排期、会议、责任同步和交付管理。Heicode 的目标不是把人类团队流程搬到 Agent 上，而是让用户从一个想法开始，由系统自动组织能力、拆解任务、调用工具、验证结果并收敛交付。

因此，本设计的基础不是：

瀑布阶段。
敏捷迭代。
Scrum 角色。
固定 Sprint。
固定流程模板。
人工项目管理表格。

本设计的基础是：

用户目标
  -> 约束识别
  -> 能力编队
  -> 动态任务图
  -> 并行执行
  -> 自我验证
  -> 失败修正
  -> 审批控制
  -> 收敛交付

可以保留阶段门，但阶段门不是开发方法论。阶段门只用于生产安全、成本控制、权限边界和验收确认。

1. 设计目标

Heicode 的最终形态是一款全流程智能开发工具。用户注册后，只需要在 Heicode 客户端输入想法，系统逐步完成产品理解、方案生成、代码开发、测试验证、部署上线、后续维护和生命周期管理。

Agnet 蜂群在这个体系里的目标是：

把用户自然语言目标转换为可执行的软件交付过程。
动态生成适合当前任务的 Agent 编队，而不是让用户选择开发流程。
让多个子 Agnet 围绕同一个目标共享上下文、领取任务、交接产物、修复失败。
让 Manager 只承担辅助控制、资源接入、审批、状态、日志、审计和用量展示。
让 Agnet 平台负责 Swarm Runtime、调度、执行、事件、产物和失败恢复。
让长期密钥只进入密钥保管器，子 Agnet 只拿短期、最小权限、可审计的访问能力。
让 CodeGW 作为模型网关和用量底座，不和子 Agnet runtime 模型策略混成一个概念。

一句话：

Heicode 负责用户目标和主体验，Manager 负责受控准备和可观测，Agnet 平台负责蜂群运行，Azure 负责基础设施。

2. 产品边界

2.1 Heicode 客户端

Heicode 客户端是主体验。

用户在客户端完成：

输入想法。
持续补充需求。
查看系统反问和建议。
确认关键决策。
审批高危操作。
接收交付结果。
发起后续维护或升级。

客户端不应该让用户配置模型供应商、AKS 参数、OpenBao 路径、完整 payload 或底层 Agent 编排。

2.2 Heicode Manager

Manager 是辅助端，不是编码主体验。

Manager 负责：

登录和账号信息。
客户端下载。
资源准备清单。
Git、SK、项目文档、云资源接入。
密钥保管器引用。
启动 Agnet 蜂群任务。
状态、日志、用量、审计。
高危审批入口。
CodeGW 用户侧能力展示。

Manager 不应该变成复杂参数后台。普通用户不应该手写完整 Agnet payload、Resource Grant、manifest、AKS namespace 或密钥路径。

2.3 Agnet 平台

Agnet 平台是蜂群运行层。

Agnet 平台负责：

创建 Swarm Run。
动态生成任务图。
动态生成 Agent 角色和 AGENT.md。
管理任务池、claim、heartbeat、handoff、complete、fail。
调度子 Agnet runtime。
执行工具调用和产物上报。
管理事件流、指标、失败恢复。
通过 AKS 运行或复用子 Agnet。

Agnet 平台不保存 Heicode 长期明文密钥，不决定用户产品体验，不直接暴露给普通用户。

2.4 CodeGW

CodeGW 是模型网关和用户可见用量底座。

CodeGW 负责：

用户可用模型。
余额和额度。
调用日志。
用量统计。
模型网关转发。

子 Agnet runtime 的模型选择属于 Agnet 平台运行策略，不应该让普通用户在客户端或 Manager 里选择模型供应商。

2.5 密钥保管器

密钥保管器负责长期凭证保管和短期租约派生。

长期凭证不进入：

Git。
Markdown。
Manager 数据库明文字段。
Agnet 平台消息体。
Agent 日志。
CodeGW。

Manager、Agnet 平台和子 Agnet 之间默认只传：

secret_ref
lease_ref
resource_ref
approval_id

3. 设计原则

3.1 目标驱动，而不是流程驱动

用户不选择“瀑布模式”或“敏捷模式”。用户只表达目标、约束、可用资源和风险偏好。

平台根据当前目标自动决定：

需要哪些能力。
是否需要拆分任务。
是否需要并行。
是否需要测试。
是否需要部署。
是否需要高危审批。
是否需要人工补充信息。

3.2 能力编队，而不是固定岗位

子 Agnet 的角色不是公司岗位，也不是 Scrum 角色。角色只是一次 Swarm Run 中的能力视角。

同一个任务可以只需要一个 Agent，也可以临时生成多个 Agent：

目标澄清 Agent。
产品理解 Agent。
架构推理 Agent。
代码实现 Agent。
测试验证 Agent。
安全检查 Agent。
部署执行 Agent。
回滚修复 Agent。
文档总结 Agent。

这些角色可以按需生成、按需结束、按需复用。

3.3 动态任务图，而不是固定工作流

Agnet 蜂群不能只是一条固定 workflow。

正确结构是动态任务图：

Goal
  -> Task A
  -> Task B
  -> Task C
       -> Task C1
       -> Task C2
  -> Verify
  -> Deploy Approval
  -> Delivery

任务图可以在执行中变化：

发现需求不清，新增澄清任务。
发现代码依赖，新增读取或重构任务。
测试失败，新增修复任务。
云资源不足，新增资源申请或审批任务。
部署失败，新增回滚或诊断任务。

3.4 受控自治，而不是完全自由

蜂群可以自主拆解、执行、交接、修复，但不能越过平台治理。

必须受控的部分：

用户身份。
资源权限。
密钥访问。
模型预算。
云资源写操作。
生产部署。
数据删除。
对外发布。
代码合并。
审计记录。

3.5 产物优先，而不是对话优先

蜂群的价值不是产生很多对话，而是产生可验证产物。

每个关键任务都应该沉淀为产物或事件：

需求摘要。
任务图。
代码 diff。
测试结果。
部署计划。
审批记录。
日志摘要。
失败原因。
回滚记录。
最终交付说明。

4. 总体运行模型

用户在 Heicode 客户端输入想法
  -> Heicode 生成初始目标和上下文
  -> Manager 检查资源准备情况
  -> 用户补齐 Git、SK、项目文档、云资源和必要授权
  -> Manager 生成启动摘要
  -> 用户确认启动
  -> Manager 请求 Agnet 平台创建 Swarm Run
  -> Agnet 平台生成动态任务图和初始能力编队
  -> 子 Agnet 从任务池 claim 任务
  -> 子 Agnet 调用工具、读取上下文、产生产物
  -> 失败时生成修复任务或交接任务
  -> 高危动作请求客户端审批
  -> 任务收敛后回传结果、日志、用量、审计

这个模型里，用户看到的是目标推进和结果，不是传统开发流程。

5. Swarm Run

Swarm Run 是一次目标执行实例。

一个 Swarm Run 包含：

用户目标。
用户身份。
会话上下文。
资源范围。
密钥引用。
能力编队。
动态任务图。
事件流。
审批策略。
成本预算。
产物索引。
收敛状态。

Swarm Run 的状态建议：

状态	含义
`created`	已创建，尚未执行
`preparing`	正在生成上下文、任务图和能力编队
`running`	正在执行
`waiting_approval`	等待高危审批
`waiting_resource`	等待资源或授权
`degraded`	部分 Agent 或工具异常，但仍可恢复
`verifying`	正在验证结果
`delivering`	正在整理交付
`completed`	已完成
`failed`	失败且不可自动恢复
`stopped`	用户或平台停止

6. 动态任务图

6.1 任务图生成

任务图由用户目标和当前上下文生成，不由固定流程模板决定。

输入包括：

用户目标。
当前代码仓库状态。
已绑定资源。
可用 SK 工具。
云资源权限。
可用模型和预算。
风险策略。
历史失败记录。

输出包括：

任务节点。
节点依赖。
所需能力。
可编辑范围。
验收条件。
风险等级。
是否需要审批。

6.2 任务节点

任务节点应该描述“要完成的事实”，而不是“某个岗位要做的动作”。

任务节点字段建议：

task_id
swarm_id
title
goal
input_refs
output_expectation
required_capability
editable_scope
resource_scope
risk_level
approval_required
status
owner_agent_id
attempt_count
max_attempts
depends_on
acceptance

6.3 任务领取

子 Agnet 从任务池领取自己有能力、有权限、上下文匹配的任务。

领取规则：

同一任务同一时间只能有一个 active owner。
claim 必须有租约和 heartbeat。
heartbeat 超时后任务释放。
任务重复投递必须幂等。
任务失败后可以重试、拆分、交接或终止。
高危任务不能被 Agent 直接执行，必须先取得审批。

6.4 任务交接

交接不是人类流程里的“交给下一个阶段”，而是动态任务图的一次状态变化。

交接发生在：

一个 Agent 完成了部分产物，需要另一个能力继续。
测试失败，需要实现 Agent 修复。
部署前需要审批。
安全检查发现风险，需要回到实现或架构任务。
当前 Agent 缺少权限或工具。

交接必须记录：

来源 Agent。
目标能力或目标 Agent。
交接原因。
输入产物。
期望输出。
当前上下文版本。
风险等级。

7. 能力编队

能力编队是按任务需要临时生成的，不是固定套用敏捷或瀑布角色。

7.1 编队输入

编队由以下信息决定：

用户目标复杂度。
代码仓库规模。
是否涉及部署。
是否涉及生产数据。
是否涉及云资源写操作。
是否需要安全审查。
是否需要 UI/产品设计。
预算和时限。

7.2 编队输出

每个子 Agnet 必须生成：

agent_id
能力说明。
AGENT.md
可用工具。
可用资源。
可编辑路径。
禁止动作。
审批策略。
停止条件。
上下文预算。
模型策略。

7.3 最小编队

MVP 不需要追求大规模 Agent。

最小编队可以是：

能力	作用
Goal/Plan Capability	理解目标、生成动态任务图、维护收敛
Build Capability	修改代码、调用工具、产出实现
Verify/Release Capability	测试验证、风险检查、部署准备、回传结果

注意：这些是能力，不是固定岗位，也不是敏捷角色。

8. 蜂群通讯

蜂群通讯不能依赖 Agent 之间自由聊天。生产级通讯必须由 Agnet 平台托管，所有关键状态都要可追踪、可重放、可审计。

8.1 通讯层

层级	作用	推荐实现
控制面通讯	Manager 创建、停止、查询 Swarm Run	HTTP API
事件通讯	Agent 状态、任务变化、日志、交接事件	NATS / JetStream
状态通讯	任务 claim、租约、重试、收敛状态	PostgreSQL + Redis Lock
产物通讯	diff、报告、日志摘要、部署记录	Git / Object Storage / Artifact 表
审批通讯	高危操作申请与客户端审批结果	Manager API + Heicode 客户端

8.2 消息原则

Agent 不直接进行不可追踪的关键点对点通讯。
所有任务分配、交接、审批、失败和完成都必须写事件。
大上下文、大日志、大文件不放进消息体，只传引用。
密钥不进入消息体，只传 secret_ref 或 lease_ref。
消息投递按 at-least-once 设计，消费端必须幂等。
同一个 swarm_id + task_id 内的关键事件必须有序号。
Manager 只接收脱敏后的事件、状态、审批请求和产物摘要。

8.3 消息信封

{
  "message_id": "uuid",
  "swarm_id": "swarm-001",
  "task_id": "task-001",
  "agent_id": "agent-001",
  "capability": "build",
  "type": "task.completed",
  "sequence": 18,
  "correlation_id": "heicode-task-id",
  "idempotency_key": "swarm-001:task-001:18",
  "timestamp": "2026-05-20T10:00:00Z",
  "payload": {},
  "payload_ref": "artifact://swarm-001/task-001/result",
  "redaction_level": "manager_safe"
}

8.4 Topic 建议

Topic	用途
`swarm.{swarm_id}.task.created`	新任务生成
`swarm.{swarm_id}.task.claimed`	任务领取
`swarm.{swarm_id}.task.completed`	任务完成
`swarm.{swarm_id}.task.failed`	任务失败
`swarm.{swarm_id}.handoff.created`	交接生成
`swarm.{swarm_id}.approval.requested`	高危审批请求
`swarm.{swarm_id}.artifact.created`	产物生成
`swarm.{swarm_id}.metric.reported`	指标上报

9. 上下文管理

蜂群上下文不是把所有历史对话塞给每个 Agent，而是为每个任务生成最小、准确、可版本化的 Context Pack。

9.1 上下文分层

上下文层	内容	保存位置
用户目标上下文	用户输入、产品目标、约束、验收标准	Heicode / Manager
Swarm Run 上下文	本次运行的预算、资源、审批、状态	Agnet 平台数据库
能力上下文	AGENT.md、工具、权限、禁止动作	Agnet 平台 / Artifact
Task 上下文	当前任务、输入、输出、依赖、验收	Task 表
代码上下文	相关文件、符号、diff、测试入口	Git / Code Index
资源上下文	Git、SK、云资源、密钥引用	Manager Resource Binding
运行记忆上下文	决策、失败、产物、待办摘要	Swarm Events / Summary

9.2 Context Pack

每个 Agent 执行任务前，平台生成 Context Pack：

{
  "context_version": 7,
  "swarm_id": "swarm-001",
  "agent_id": "agent-001",
  "capability": "build",
  "task": {
    "task_id": "task-023",
    "goal": "实现资源绑定表单校验",
    "acceptance": ["前端构建通过", "密钥字段不回显"]
  },
  "constraints": {
    "editable_paths": ["web/default/src/features/resources"],
    "forbidden_actions": ["production_deploy"],
    "approval_required": ["secret_read", "cloud_write"]
  },
  "resources": {
    "git_refs": [],
    "sk_refs": [],
    "secret_refs": []
  },
  "prior_artifacts": [],
  "failure_history": []
}

9.3 上下文原则

PostgreSQL 保存权威状态，Redis 只做热缓存和锁。
Git 保存代码事实，Artifact 保存大产物，密钥保管器只保存密钥。
每次任务开始使用不可变 context_version。
任务完成后生成摘要，更新 Swarm Run 记忆。
代码场景优先传文件路径、符号、diff、测试入口，不传整仓内容。
资源和密钥只传引用与权限边界，不传明文。
用户、资源、审批、预算必须隔离，不能跨用户复用上下文。
上下文过期后必须重新拉取，不能继续使用旧权限。

9.4 上下文更新闭环

用户目标 -> 初始上下文
  -> Swarm Run 上下文
  -> 动态任务图
  -> Context Pack
  -> Agent 执行
  -> 事件和产物
  -> 运行记忆摘要
  -> 新的 Context Pack
  -> 收敛交付

10. 代码场景调优

代码开发场景的蜂群调优不是只调 prompt，而是调任务颗粒度、代码检索、工具权限、测试策略、并发写入、审批边界和失败恢复。

10.1 调优环节

环节	调优目标	调优方式
目标理解	避免从错误需求开始	生成目标摘要、风险点、待确认问题
任务拆分	任务够小、边界清楚、可验收	按能力、文件、模块、风险拆分
代码检索	不读错文件、不漏依赖	建立 repo map、符号索引、测试入口索引
上下文打包	不超长、不缺约束	只放相关路径、diff、接口、验收标准
并发写入	减少冲突	每个任务声明 editable paths 和 conflict policy
工具调用	能做事但不能越权	按能力授予 Git、SK、云资源、Secret Ref 权限
测试策略	快速发现失败并闭环	targeted test -> package test -> build -> smoke
代码审查	降低回归和安全风险	自动 review 权限、密钥、并发、错误处理
部署准备	可回滚、可审批	生成部署计划、变更摘要、回滚步骤
高危操作	不让 Agent 自动越权	客户端审批生产部署、删除资源、读取短期凭证

10.2 运行参数

参数	作用
`agent_count`	控制同时工作的 Agent 数量
`max_parallel_tasks`	控制并发任务数量
`task_timeout_minutes`	限制单任务卡死
`max_iterations`	限制反复修复次数
`handoff_limit`	限制交接循环
`context_token_budget`	限制 Context Pack 大小
`retry_count`	控制失败重试
`approval_timeout_minutes`	控制等待审批时间
`test_depth`	控制验证深度

10.3 调优指标

任务一次通过率。
测试失败后平均修复轮次。
上下文缺失导致的失败次数。
代码冲突次数。
重复修改同一文件次数。
审查发现的 P0/P1 问题数量。
从用户想法到可部署产物的周期。
单次 Swarm Run 成本。
高危审批命中率与误触发率。

10.4 最小生产策略

第一期应限制自治范围：

默认 3 个核心能力：目标/计划、构建、验证/发布。
不允许多个 Agent 同时改同一目录，除非任务图明确声明不冲突。
生产部署、删除资源、读取短期高危凭证默认需要审批。
代码产物必须经过测试，或明确记录未测试原因。
失败必须沉淀为事件和摘要，供下一轮 Context Pack 使用。

11. Manager 与 Agnet 平台接口

接口不是为了让用户配置底层参数，而是让 Manager 把用户目标、资源引用、审批策略和预算交给 Agnet 平台。

11.1 Manager -> Agnet 平台

核心接口：

接口	目的
`POST /api/swarms`	创建 Swarm Run
`GET /api/swarms/{swarm_id}`	查询运行状态
`GET /api/swarms/{swarm_id}/events`	查询事件流
`GET /api/swarms/{swarm_id}/artifacts`	查询产物
`POST /api/swarms/{swarm_id}/stop`	停止运行
`POST /api/swarms/{swarm_id}/approvals/{approval_id}`	回传审批结果

创建 Swarm Run 请求示例：

{
  "request_id": "uuid",
  "heicode_task_id": "task-id",
  "user_context": {
    "user_id": "heicode-user-id",
    "email": "user@example.com",
    "channel_id": "codegw-channel-id"
  },
  "goal": "用户目标",
  "resource_refs": {
    "git": [],
    "sk": [],
    "project_docs": [],
    "cloud": []
  },
  "secret_refs": [
    {
      "name": "azure-credential",
      "secret_ref": "bao://example/ref"
    }
  ],
  "approval_policy": {
    "production_deploy": "client_required",
    "production_secret_access": "client_required"
  },
  "budget": {
    "max_model_cost": 20,
    "max_runtime_minutes": 60,
    "max_iterations": 20
  },
  "runtime_preferences": {
    "mode": "goal_driven_swarm",
    "max_parallel_tasks": 3
  }
}

11.2 Agnet 平台 -> Manager

核心回调：

接口	目的
`POST /api/agnet/callbacks/swarm-events`	回传事件
`POST /api/agnet/callbacks/approval-requests`	请求高危审批
`POST /api/agnet/callbacks/artifacts`	回传产物
`POST /api/agnet/callbacks/usage`	回传用量
`POST /api/agnet/callbacks/status`	回传总体状态

事件示例：

{
  "swarm_id": "swarm-uuid",
  "event_id": "event-uuid",
  "type": "task.completed",
  "agent_id": "agent-001",
  "task_id": "task-2",
  "message": "构建任务完成",
  "timestamp": "2026-05-26T10:00:00Z",
  "metadata": {
    "artifact_ids": ["artifact-1"],
    "handoff_to_capability": "verify_release"
  }
}

审批请求示例：

{
  "swarm_id": "swarm-uuid",
  "approval_id": "approval-uuid",
  "type": "production_deploy",
  "title": "请求部署到生产环境",
  "risk": "high",
  "resource_refs": ["azure-prod-aks"],
  "expires_at": "2026-05-26T10:15:00Z"
}

11.3 接口安全

服务端身份认证。
X-Correlation-Id 全链路追踪。
创建接口使用 Idempotency-Key。
回调接口使用签名或服务 token。
请求体不得出现长期明文密钥。
日志不得输出 token、password、private_key、connection_string。
所有事件必须可审计。

12. 数据模型

Agnet 平台需要围绕 Swarm Run 建模，而不是围绕传统项目管理建模。

12.1 `swarm_runs`

保存一次目标运行。

关键字段：

id
heicode_task_id
user_id
channel_id
goal
status
budget
approval_policy
context_version
created_at
started_at
finished_at
failure_reason

12.2 `swarm_capabilities`

保存本次运行生成的能力编队。

关键字段：

id
swarm_id
capability
agent_md
runtime_ref
status
last_heartbeat_at
model_profile
tool_scope
resource_scope
editable_scope

12.3 `swarm_tasks`

保存动态任务图。

关键字段：

id
swarm_id
parent_task_id
title
goal
required_capability
status
owner_agent_id
attempt_count
max_attempts
priority
depends_on
input_artifacts
output_artifacts
acceptance

12.4 `swarm_events`

保存事件流。

关键字段：

id
swarm_id
agent_id
task_id
type
message
metadata
sequence
created_at

12.5 `swarm_artifacts`

保存产物索引。

关键字段：

id
swarm_id
task_id
agent_id
type
name
uri
checksum
metadata

12.6 `swarm_approvals`

保存高危审批。

关键字段：

id
swarm_id
agent_id
task_id
action
risk_level
resource_refs
status
requested_at
approved_by
approved_at
expires_at

13. Azure 落地

13.1 AKS

AKS 负责运行：

Agnet 平台服务。
子 Agnet runtime。
NATS/JetStream。
Prometheus。
运行时辅助服务。

MVP 可以按用户或 Swarm Run 打 label：

heicode-user-id=<user_id>
swarm-id=<swarm_id>
capability=<capability>
managed-by=agnet-platform

安全要求提高后，再升级为每用户或每 Swarm Run namespace。

13.2 Azure PostgreSQL

保存最终事实：

Swarm Run。
动态任务图。
能力编队。
事件。
审批。
产物索引。
审计。
用量。

PostgreSQL 是最终事实源，不能用 Redis 替代。

13.3 Redis

Redis 负责：

claim 锁。
heartbeat 缓存。
幂等 key。
短期状态。
热点状态缓存。

Redis 数据丢失不应导致最终状态丢失。

13.4 NATS/JetStream

NATS/JetStream 负责：

任务事件。
Agent 状态通知。
交接事件。
指标事件。
回调异步化。

NATS 不是最终事实源。关键事件必须落 PostgreSQL。

13.5 密钥保管器

长期凭证进入密钥保管器。

子 Agnet 不应长期保存：

云 access key。
数据库密码。
Git token。
OpenBao token。
CodeGW key。

高危操作通过审批后，平台可以派生短期凭证，并通过受控方式注入 runtime。

14. 安全边界

安全红线：

不在 Git、Markdown、日志、事件、错误信息中写入真实密钥。
Manager 数据库只保存 secret_ref，不保存明文长期密钥。
Agnet 平台不接收长期明文密钥。
子 Agnet 不长期保存凭证。
高危操作必须经过审批。
回调必须认证和可审计。
Agent 只能使用被授权的 Git、SK、云资源和工具。
任何资源越权都必须失败并写审计。
CodeGW key 不直接暴露给普通用户或子 Agnet。

15. 指标体系

蜂群指标不能只看 Pod 是否 Running。必须看协作是否产生价值。

当前 swarm-minimal 的可执行指标阈值以 AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md 为准。本节描述目标平台指标体系，并补充当前最小原型已经采用的成功值，避免把“可观测”误读成“已达标”。

15.1 运行效率

指标	含义
Swarm 完成率	成功完成的 Swarm Run 比例
平均完成时间	从创建到完成的耗时
平均任务迭代次数	每个任务的修复循环次数
Agent 利用率	Agent 忙碌时间占比
任务等待时间	task created 到 claimed 的时间
Handoff 次数	子任务交接次数
Handoff 失败率	交接后失败或超时比例

15.2 交付质量

指标	含义
测试通过率	生成或执行测试的通过比例
代码检查通过率	lint、review、security check 通过比例
返工次数	任务被打回或重复修复次数
artifact 完整度	需求、代码、测试、部署记录是否齐全
人工介入次数	非审批类人工介入次数

15.3 稳定性

指标	含义
Agent 启动成功率	子 Agnet runtime 成功启动比例
Agent 崩溃恢复时间	runtime 崩溃到恢复或任务释放时间
任务重试成功率	失败任务经重试后成功比例
队列积压长度	待处理任务数量
状态一致性错误	Manager、Agnet、DB 状态不一致次数

15.4 成本与安全

指标	含义
模型成本	每个 Swarm Run 的模型消耗
Runtime 成本	AKS CPU、内存、网络、存储消耗
预算超限次数	超过用户或任务预算次数
高危审批覆盖率	高危动作进入审批的比例
明文密钥泄露次数	必须为 0
未授权资源访问次数	必须为 0

15.5 当前最小原型验收阈值

指标组	当前最小原型成功值
AQS 本地门禁	A01-A09 全部 PASS；`unittest discover` 当前 45 项全部通过
S07 live 外部代码链	7 个任务完成；14 项 checks 全 PASS；`accepted_score >= 0.75`；共识轮数 `>=2`
S09 扩缩容	`3/5/7` Agent 下均满足 `completed_tasks=2n`、`failed_tasks=0`、`duplicate_claims=0`
S09 候选融合	`min_score=0.5`；保留 `quality/coverage`；过滤 `noise=0.2`
S09 互相质询	`threshold=0.7`；`min_margin=0.2`；第一轮不收敛，最后一轮收敛
S10 六特征	F01-F06 全部 PASS；成功值见 `AGENT_SWARM_INDICATOR_TEST_MATRIX.zh-CN.md`
密钥安全	Git、Markdown、报告、日志和 artifact 中真实长期密钥数必须为 `0`

16. 最小验证

蜂群 MVP 的最小验证不是“创建 3 个 Pod”，也不是“跑完一条 workflow”。它必须证明目标驱动、动态任务、能力协作、事件回传、审批和产物闭环。

最小验证流程：

1. 用户在 Heicode 输入一个可实现的软件目标
2. Manager 检查资源准备并生成启动摘要
3. 用户点击启动 Agnet
4. Manager 调用 POST /api/swarms
5. Agnet 平台创建 Swarm Run
6. Agnet 平台生成动态任务图
7. Agnet 平台生成最小能力编队
8. 一个子 Agnet claim 构建任务
9. 子 Agnet 产出代码或文档 artifact
10. 验证能力接手测试或检查任务
11. 失败时生成修复任务并回流
12. 高危动作触发 Heicode 客户端审批
13. 审批结果回到 Agnet 平台
14. 最终状态、事件、日志、artifact、用量、审计回传 Heicode

验收通过必须满足：

项	最小标准
创建	`POST /api/swarms` 返回 `swarm_id`
任务图	至少生成 2 个可追踪任务
协作	至少发生 1 次交接或失败回流
产物	至少产生 1 个 artifact
事件	Heicode 可查询完整事件流
状态	Heicode 与 Agnet 平台状态一致
审批	高危动作进入审批
安全	无明文长期密钥
停止	Swarm 可停止，任务和 runtime 状态可解释

17. 失败恢复

必须支持以下失败场景：

场景	处理方式
子 Agnet 启动失败	Swarm Run 标记 degraded，重试或替换 runtime
heartbeat 超时	释放任务，其他同能力 Agent 可 claim
工具调用失败	重试，超过次数后生成失败事件
测试失败	生成修复任务并回流
预算不足	Swarm 暂停，等待用户确认或终止
高危审批拒绝	对应任务失败或改走安全方案
NATS 暂时不可用	事件可从 PostgreSQL 补偿恢复
Redis 丢失	通过 PostgreSQL 重建任务状态
上下文过期	停止当前任务，重新生成 Context Pack

18. 阶段边界

MVP 必须完成

Swarm Run 创建。
动态任务图。
能力编队。
任务 claim。
heartbeat。
交接或失败回流。
artifact。
事件流。
状态查询。
高危审批。
用量回传。
审计记录。

MVP 可以延期

大规模多 Swarm 调度优化。
每个 Swarm 独立 namespace。
复杂 UI 可视化编排。
多模型自动竞价。
自学习 Agent 角色演化。
完全自动复杂产品规划。
全自动生产发布。

19. 最终判断标准

如果一个实现只做到以下内容，不算蜂群落地：

只创建多个 Agent Pod。
只按固定顺序执行 workflow。
只把任务写进文档。
只展示部署成功。
只有模拟执行结果。
只是把敏捷或瀑布换成 Agent 名字。

如果一个实现做到以下内容，才算蜂群 MVP 落地：

从用户目标生成动态任务图。
按任务需要生成能力编队。
子 Agnet 从共享任务池领取任务。
至少发生一次交接或失败回流。
事件、日志、artifact、用量、审计全链路可查。
一个 Agent 失败后，任务能释放、重试或失败可解释。
高危操作进入审批。
用户不需要看底层完整参数。
Heicode 能展示完整运行闭环。

20. 结论

Agnet 蜂群不是传统开发流程自动化，也不是瀑布、敏捷、Scrum 的 Agent 化版本。

它应该是：

目标驱动的受控自治执行系统

Heicode 提供用户目标和主体验，Manager 提供资源准备、启动、审批、状态、用量和审计，Agnet 平台提供 Swarm Runtime，Azure 提供运行基础设施，密钥保管器提供凭证安全，CodeGW 提供模型网关和用量底座。

32 KiB Raw Blame History Unescape Escape

Agnet 受控蜂群设计原理

当前仓库状态（2026-05-16）

0. 核心修正

1. 设计目标

2. 产品边界

2.1 Heicode 客户端

2.2 Heicode Manager

2.3 Agnet 平台

2.4 CodeGW

2.5 密钥保管器

3. 设计原则

3.1 目标驱动，而不是流程驱动

3.2 能力编队，而不是固定岗位

3.3 动态任务图，而不是固定工作流

3.4 受控自治，而不是完全自由

3.5 产物优先，而不是对话优先

4. 总体运行模型

5. Swarm Run

6. 动态任务图

6.1 任务图生成

6.2 任务节点

6.3 任务领取

6.4 任务交接

7. 能力编队

7.1 编队输入

7.2 编队输出

7.3 最小编队

8. 蜂群通讯

8.1 通讯层

8.2 消息原则

8.3 消息信封

8.4 Topic 建议

9. 上下文管理

9.1 上下文分层

9.2 Context Pack

9.3 上下文原则

9.4 上下文更新闭环

10. 代码场景调优

10.1 调优环节

10.2 运行参数

10.3 调优指标

10.4 最小生产策略

11. Manager 与 Agnet 平台接口

11.1 Manager -> Agnet 平台

11.2 Agnet 平台 -> Manager

11.3 接口安全

12. 数据模型

12.1 swarm_runs

12.2 swarm_capabilities

12.3 swarm_tasks

12.4 swarm_events

12.5 swarm_artifacts

12.6 swarm_approvals

13. Azure 落地

13.1 AKS

13.2 Azure PostgreSQL

13.3 Redis

13.4 NATS/JetStream

13.5 密钥保管器

14. 安全边界

15. 指标体系

15.1 运行效率

15.2 交付质量

15.3 稳定性

15.4 成本与安全

15.5 当前最小原型验收阈值

16. 最小验证

17. 失败恢复

18. 阶段边界

MVP 必须完成

MVP 可以延期

19. 最终判断标准

20. 结论

32 KiB

Raw Blame History

12.1 `swarm_runs`

12.2 `swarm_capabilities`

12.3 `swarm_tasks`

12.4 `swarm_events`

12.5 `swarm_artifacts`

12.6 `swarm_approvals`