Agent蜂群指标量化与标准 v0.1

0 Open

0 Closed

1. 概述

本标准用于量化评估 Agent Swarm（Agent 蜂群）系统的能力、效率、协作质量、涌现能力及治理水平。

目标：

建立统一的蜂群评测体系
支持不同 Agent Framework 横向比较
支持持续优化与回归测试
支持 Benchmark 排行榜建设

2. Benchmark 总体公式

2.1 综合评分

Benchmark_Agent =

λ1 × S_swarm

λ2 × G_E
λ3 × R
λ4 × O
λ5 × Gov

其中：

指标	含义
S_swarm	蜂群能力
G_E	涌现增益
R	奖励函数
O	可观测性
Gov	治理能力

3. ACO → Agent Swarm 理论映射

ACO 概念	Agent Swarm 映射
节点 i	软件状态 s
节点 j	动作 a
蚂蚁 k	Agent 角色 r
信息素 τ	历史有效性
启发式 η	当前收益
α	历史经验权重
β	上下文权重

4. 决策层指标

4.1 信息素指标 τ

τ(s,a,r)

= f(success, quality, cost, time, risk, rollback, acceptance)

建议量化：

τ = w1×Success +w2×Quality +w3×Acceptance -w4×Cost -w5×Time -w6×Risk -w7×Rollback

数据来源

因子	数据来源
Success	Task Complete
Quality	测试与CI/CD
Cost	Token与资源消耗
Time	执行耗时
Risk	安全事件
Rollback	回滚记录
Acceptance	Reviewer验收

4.2 启发式指标 η

η(s,a,r)

= g(match, urgency, dependency, resource, risk, budget, confidence)

建议量化：

η = w1×Match +w2×Urgency +w3×Dependency +w4×Resource +w5×Confidence -w6×Risk -w7×BudgetPressure

数据来源

因子	数据来源
Match	能力匹配度
Urgency	任务优先级
Dependency	DAG依赖
Resource	資源授权
Risk	风险引擎
Budget	Token预算
Confidence	Agent自评

4.3 决策概率

P(a)

τ(a)^α × η(a)^β

Σ[τ(a_i)^α × η(a_i)^β]

决策质量

P_decision

= Selected_Action_Probability × 100

5. 执行层指标

5.1 奖励函数

R = w1·S_task +w2·Q_quality +w3·V_speed +w4·E_cost +w5·R_robust +w6·G_governance -w7·P_risk -w8·P_rework

5.2 任务完成度

S_task = CompletedTasks / TotalTasks × 100

5.3 质量指标

Q_quality = 0.4×TestPassRate +0.3×CodeReviewScore +0.3×UserAcceptance

5.4 速度指标

V_speed = 100 × TargetTime / ActualTime

5.5 成本指标

E_cost = 100 × ExpectedCost / ActualCost

5.6 鲁棒性指标

R_robust = RecoveredFailures / TotalFailures × 100

5.7 治理指标

G_governance = CompliantActions / SensitiveActions × 100

6. 蜂群层指标

6.1 蜂群评分

S_swarm = 0.25×S_completion +0.20×S_gain +0.15×S_collaboration +0.10×S_communication +0.10×S_cost +0.10×S_robustness +0.10×S_governance

6.2 Completion

S_completion = CompletedTasks / TotalTasks × 100

6.3 Collaboration

S_collaboration = 0.5×HandoffSuccessRate +0.3×DependencyResolutionRate +0.2×WorkloadBalanceScore

6.4 Communication

S_communication = SuccessfulMessages / TotalMessages × 100

6.5 Cost

S_cost = 100 × Budget / ActualUsage

6.6 Robustness

S_robustness = RecoveredFailures / TotalFailures × 100

6.7 Governance

S_governance = CompliantOperations / TotalOperations × 100

7. 涌现增益（Emergence Gain）

7.1 原始增益

G_E = Q_swarm - Q_base

Q_base 可以是：

Single Agent
Strong Agent
Chain Agent
Sub-Agent

7.2 成本归一化增益

G_E,c = (Q_swarm / C_swarm)

(Q_base / C_base)

目的：

避免通过无限增加 Agent 数量获得虚假的能力提升。

8. 数据采集标准

数据来源：

Agent Runtime
Task Logs
Handoff Logs
WebSocket Logs
Git Activity
CI/CD Results
Audit Logs
Infrastructure Metrics

推荐平台：

Prometheus
OpenTelemetry
ClickHouse
Elasticsearch

9. 指标采集接口

from dataclasses import dataclass

@dataclass
class SwarmMetrics:
    p_decision: float
    reward: float
    completion: float
    gain: float
    collaboration: float
    communication: float
    cost: float
    robustness: float
    governance: float

class SwarmMetricsCollector:
    async def collect(self) -> SwarmMetrics:
        pass

10. Benchmark Protocol

Baseline A

Single Agent

Baseline B

Strong Agent

Baseline C

Chain Agent

Baseline D

Sub-Agent

Experimental Group

Swarm Agent

所有实验统一采集：

Completion
Quality
Cost
Time
Robustness

11. Leaderboard 评分标准

建议同时展示：

Benchmark_Agent
S_swarm
G_E
G_E,c
Reward
Cost Efficiency

支持：

Coding
Refactoring
Architecture
DevOps
Bug Fix

等不同场景排行榜。

12. 标准结论

本标准将 ACO 理论、Agent Swarm 协作机制、奖励函数、能力增益模型与 Benchmark Protocol 统一到一个可计算、可观测、可复现的评测框架中，用于衡量 Agent 蜂群系统的真实工程能力。

heicode 项目书

0 Open

0 Closed

Heicode 项目书

版本：v0.2（正式）
日期：2026-05-30
文件位置：项目根目录 /Volumes/macOS/GO/heicodeall/项目书.md
编制依据：heicodedocs/ 产品文档站内容、heicode-mananger/ 管理端与产品资料、HeiCode-Swarm/ 蜂群运行时文档、heicode-macos-release/ macOS 客户端发布仓库。
说明：本文用于立项、内部对齐、客户沟通和后续实施拆解。涉及“已完成 / 进行中 / 规划中”的状态，按当前仓库文档与代码状态谨慎表述，不把未完整落地能力描述成已上线能力。

执行摘要
项目背景与建设必要性
项目定位与总体目标
建设范围与系统边界
用户对象与典型场景
产品方案
技术架构方案
安全、凭证与审计方案
计费、资源与商业化设计
当前实现基础
实施路线图
验收指标
运营与交付方案
风险分析与应对
组织分工建议
附录：术语、文档与仓库索引
参考文献与外部依据

1. 执行摘要

1.1 项目名称

Heicode：面向软件生命周期的智能开发平台

1.2 一句话定位

Heicode 让用户从一个想法开始，组织 AI 开发团队，安全接入自己的代码、文档、技能和云资源，完成从产品设计到生产部署的软件生命周期。

1.3 项目概述

Heicode 是一款覆盖软件生命周期的智能开发 Code 工具。它不是单个模型聊天窗口，也不是单纯的 IDE 插件、模型网关后台或 Agent 控制台，而是把需求澄清、产品文档、原型描述、代码开发、代码检查、部署、观测、维护和升级组织成一条可编排、可审计、可持续推进的交付链路。

用户注册登录后，可以在 Heicode 客户端输入产品想法或开发任务。Heicode Manager 负责资源绑定、权限分配、Agnet 部署、模型用量、状态和审计；Agnet 平台负责在 AKS 上运行子 Agnet，执行开发、测试、修复、交付和部署；CodeGW 提供模型网关和计费能力；密钥保管器负责长期凭证托管，并按审批和权限派生短期访问能力。

1.4 项目核心价值

从想法到上线：把自然语言想法转成需求、计划、任务、代码和部署结果。
AI 团队化协作：用 Product、Architect、Frontend、Backend、Reviewer、Ops 等子 Agnet 分工承接不同环节。
真实资源可用：让 Agent 能在授权范围内使用 Git、项目文档、SK 技能和云资源，而不是停留在离线问答。
安全边界可控：长期密钥进入密钥保管器，子 Agnet 只获得短期、最小权限、可审计凭证。
成本与用量可见：统一展示模型、余额、额度、调用日志、任务消耗和运行时使用量。
交付可追溯：资源、权限、模型、任务状态、审批、日志、事件和交付物形成审计链路。

1.5 当前项目状态概览

模块	当前基础	状态判断
Heicode Manager	已有产品资料、登录对接、资源/Agnet/计费/审计方向文档，基于 Go 的管理端和网关代码	主线边界已收敛，资源模型与 Secret Broker 仍需完整落地
Heicode 客户端	macOS 发布仓库已有 v0.4.18，近期持续修复登录、模型探活、额度加载和凭证持久化问题	已具备发布基础，仍需与 Manager / Agnet 执行闭环继续对齐
HeiCode Swarm	单 Agent MVP 已跑通，Runtime Bridge 已有核心接口，多 Agent DAG 可灰度启用	执行平台具备基础，生产化和真实部署联调需继续推进
CodeGW	承担模型网关、额度、余额、用量和日志能力	应保持内部底座，不向普通用户开放后台
Secret Store	文档明确 Azure Key Vault / Vault 方向，`secret_ref` 为核心边界	需要完成后端 Secret Broker 与运行时短期凭证注入

1.6 项目初心：从 Claude Code 到 Heicode

Heicode 的起点，来自一次真实而强烈的使用体验。

当我真正使用 Claude Code 这类产品后，第一次清楚感受到传统开发方式正在被改写。过去的软件开发，是程序员一行一行编写代码、调试、提交、部署；而 Claude Code 展示出的新方式，是开发者可以通过对话描述目标，让 AI 逐步完成产品实现。这种从“写代码”转向“用对话完成产品”的体验，对程序员和广大开发者本身就是一次冲击，也让我真正意识到 AI 编程不是辅助工具的小修小补，而可能成为软件生产方式的下一次迁移。

我喜欢 Claude Code 带来的这种冲击，也认可它让开发者重新思考“代码到底应该由谁写、开发者真正应该关注什么”。但我不喜欢的是，产品能力被账号、封禁、平台策略和外部服务中断所限制。我的一次使用在约 20 天后被迫中止，这件事直接触发了我做 Heicode 的想法：如果 AI 开发会成为新的基础生产力，那么开发者不能把自己的开发连续性完全交给一个不可控账号和单一外部入口。

在我看来，当前阶段的 AI 开发有几个判断：

传统开发的标准化仍然存在。需求、设计、开发、测试、发布、审计、维护这些环节不会因为 AI 出现而消失，只是承接它们的角色和方式会变化。
AI 加持下的软件开发应该走向完整自动化。Claude Code 和 Codex 已经证明“对话驱动代码”可行，但它们还没有把产品、资源、权限、部署、审计和维护做成完整生命周期。
开发者应该更多关注产品方向，而不是具体代码细节。未来开发者的核心工作，应从逐行写代码转向定义目标、判断方向、确认约束、审批风险和迭代产品。代码可以在一个或多个迭代周期中由 AI 团队完成。
运行 Agent 的基础设施不应只在本地。如果 Agent 的能力被限制在本地机器、个人环境和临时会话里，开发者的能力在底座层面就被限制了。真正的 AI 开发需要云端运行时、任务状态、资源池、日志、指标、权限和可恢复能力。
开发过程必须可控、可管理、可回溯。AI 能写代码不等于可以无边界执行。真实生产环境需要知道谁发起了任务、哪个 Agent 使用了什么资源、是否经过审批、产生了什么变更、消耗了多少模型额度，以及出了问题如何追踪和复盘。

因此，Heicode 不是为了复刻 Claude Code，也不是只做一个替代账号风险的壳。Heicode 要做的是把 AI 开发从“个人本地对话工具”推进到“可控、可管理、可回溯的软件生命周期平台”。它既承认传统工程标准化的价值，又把 AI Agent 放到更完整的产品、权限、资源、部署和审计体系中，让开发者真正把注意力放在产品方向和交付结果上。

2. 项目背景与建设必要性

2.1 行业背景

AI 已经能在局部场景中完成代码生成、解释、重构和测试建议，但软件交付并没有因此自动变简单。真实的软件项目仍然包含需求澄清、架构设计、代码协作、权限管理、测试回归、部署运维、安全审计、成本控制和长期维护等环节。

当前市场上常见的 AI 编程工具大多集中在以下形态：

类型	价值	局限
聊天式 AI 工具	快速回答问题、生成片段	与真实 Git、云资源、部署系统脱节
IDE 插件 / 终端 Agent	适合开发者本地协作	对非工程用户不友好，团队权限和审计较弱
单 Agent 编程助手	能完成中小任务	大型任务拆解、并行、审批和可追溯能力有限
DevOps / CI 平台	管理构建、部署和运维	缺少自然语言任务理解和 AI 团队编排
模型网关后台	解决模型渠道和计费	不是用户完成软件交付的产品入口

因此，市场缺口不是“再做一个能写代码的聊天窗口”，而是构建一个能把产品、代码、权限、模型、资源、部署和维护组织成统一流程的平台。

2.2 用户痛点

独立开发者

独立开发者往往有产品想法，但缺少完整工程团队。现有 AI 工具可以生成代码片段，却难以稳定完成需求拆解、项目结构、前后端开发、部署上线和后续维护。

创业团队

创业团队需要快速验证和迭代，但人力有限。团队希望使用 AI 提升开发效率，却又担心 AI 对真实代码仓库和云资源的操作不可控。

企业创新团队

企业团队已有 Git、文档、云账号、数据库和部署环境，但协作链路复杂，权限边界严格。AI 若不能接入这些资源，就只能停留在“建议”；若直接接入，又存在凭证泄露、误操作和审计缺失风险。

技术负责人

技术负责人不仅关心“能不能写代码”，更关心谁使用了什么资源、消耗了多少模型额度、是否经过审批、是否能回滚、失败原因能否追踪。

2.3 建设必要性

Heicode 项目的建设必要性体现在四个方面：

交付链路需要贯通：从想法到上线不能分散在聊天工具、Git、云控制台、模型后台和人工沟通中。
AI 协作需要工程化：多 Agent 需要角色、任务图、权限、状态、日志、回调和恢复机制。
真实资源接入必须安全：Git token、云密钥、数据库密码不能进入 Markdown、日志、前端或子 Agnet 长期状态。
商业化需要统一计量：模型、运行时、任务、Agent 数量、团队协作和资源池需要形成可理解、可售卖、可审计的计费模型。

2.4 外部研究与产业依据

为了让 Heicode 不只是产品设想，而是能形成有学术支撑和工程落地路径的项目，本项目可放在 Agentic Software Engineering（智能体软件工程） 和 Agentic SDLC（智能体软件生命周期） 的研究方向下理解。

2.4.1 从代码补全到委托式执行

Agentic Software Engineering 的核心变化，是软件工程 AI 的对象从“补全一行代码或一个函数”转向“在仓库、功能、任务和算法粒度上进行委托式执行”。外部综述研究将 Claude Code、OpenAI Codex CLI、Devin、OpenHands、SWE-agent、MetaGPT、ChatDev 等系统归入这一趋势，并提出传统 SDLC 正在向 Agentic SDLC 演进：人类更多承担意图定义、治理、审查和批准，Agent 承担任务拆解、代码修改、测试、验证和交付执行。

这与 Heicode 的定位一致：Heicode 不把 AI 作为代码补全工具，而是把 AI Agent 放入需求、资源、权限、开发、部署、审计和维护的全流程。

2.4.2 SWE-bench 证明真实软件工程不是简单代码生成

SWE-bench 将真实 GitHub issue 和 pull request 转化为评测任务，要求模型在给定代码库和问题描述后生成可通过测试的补丁。该评测强调真实软件工程任务常常需要跨函数、跨类、跨文件修改，要求模型理解长上下文、使用执行环境并完成复杂推理。

这说明 Heicode 的落地方向不能只围绕“生成代码片段”，而必须建设：

仓库级上下文理解。
多文件变更能力。
测试和验证环境。
Git 工作流。
可回放的任务记录。
失败恢复和人工审批机制。

2.4.3 多 Agent 软件开发已有研究基础

MetaGPT、ChatDev、AgileCoder、HyperAgent 等研究和框架，已经从不同角度验证了多 Agent 参与软件开发的可行性：

MetaGPT 强调把标准作业流程（SOP）编码进多 Agent 协作，让 Product Manager、Architect、Engineer 等角色通过结构化产物协作。
ChatDev 把软件开发模拟为虚拟软件公司，通过角色对话推进设计、编码、测试等阶段。
AgileCoder 将敏捷方法引入多 Agent 开发流程，让 Product Manager、Scrum Master、Developer、Tester 等角色围绕 sprint 协作。
HyperAgent 将软件工程任务拆成 Planner、Navigator、Code Editor、Executor 等角色，覆盖定位、编辑和执行验证。

这些研究给 Heicode 的三代 Agnet 演进提供了外部依据：链式、Sub 和蜂群不是空想，而是可以分别对应流水线式工作流、子任务协作式工作流和多 Agent 图式编排。

2.4.4 安全治理是 Agentic 系统的前置条件

OWASP LLM Top 10 2025 将 Excessive Agency（过度代理能力） 作为重要风险，强调当 LLM / Agent 拥有过多工具、权限或自主行为能力时，可能导致高影响操作失控。NIST AI RMF 也强调 AI 风险管理应覆盖 Govern、Map、Measure、Manage，并要求定义人机配置、角色责任和人工监督流程。NIST Zero Trust Architecture 则强调不基于网络位置或资产归属授予隐式信任，而是对每次访问进行认证、授权和最小权限控制。

这直接支撑 Heicode 的安全设计：

子 Agnet 不拿长期密钥。
Resource Grant 明确角色、资源、动作、范围和 TTL。
高危操作必须客户端审批。
secret_ref 替代明文密钥。
每一次资源访问都应可追踪、可撤销、可审计。

2.4.5 落地效果需要工程指标，而不是只看演示

DORA 软件交付指标提供了衡量工程效率和稳定性的通用框架，包括变更交付时间、部署频率、失败恢复时间、变更失败率和返工率。SLSA 供应链安全框架强调软件制品需要 provenance（来源与构建过程证明），以保证制品可追溯、可验证、可审计。

因此 Heicode 的项目验收不应只看“能不能生成代码”，还应看：

从任务创建到可验证变更的时间。
从 commit 到部署的时间。
Agent 生成变更的测试通过率。
高危操作审批覆盖率。
任务失败后的恢复时间。
交付物和构建产物是否具备 provenance。
审计记录是否能还原资源、模型、角色和操作链路。

3. 项目定位与总体目标

3.1 产品定位

Heicode 的最终形态是一款面向全流程智能开发的 SaaS Code 工具。用户无需理解底层模型供应商、CodeGW 后台、密钥系统或 Kubernetes 细节，只需要在 Heicode 中表达目标、授权资源、确认权限和审批高危操作。

平台逐步完成：

团队生成。
产品文档。
原型描述。
代码开发。
代码检查。
部署到生产并对外提供服务。
后续定期维护和升级。
软件生命周期管理。

3.2 建设总目标

建设一个可以支撑个人、团队和企业使用的 AI 软件交付平台，实现：

用户从自然语言想法启动项目或任务。
平台生成需求摘要、产品文档、任务计划和角色建议。
用户绑定 Git、项目文档、SK、云资源等上下文。
Manager 生成资源授权、权限清单和部署请求。
Agnet 平台按角色执行开发、测试、修复、交付和部署。
客户端承担持续对话、反馈查看和高危审批。
CodeGW 提供模型、余额、额度和调用日志。
密钥保管器托管长期凭证，运行时只使用短期授权。
所有关键动作可审计、可回放、可追踪。

3.3 阶段目标

阶段	目标	交付结果
MVP 阶段	跑通登录、客户端、资源绑定、模型展示、单 Agent 执行和状态回传	可演示的从想法到任务执行闭环
P1 阶段	统一资源模型和 Resource Grant	资源绑定、授权、撤销、manifest 生成
P2 阶段	建立 Secret Broker 与密钥保管器	`secret_ref` 写入、脱敏、轮换、撤销
P3 阶段	接入 AKS 运行时身份	子 Agnet 按最小权限访问授权资源
P4 阶段	解耦并产品化 CodeGW 能力	用户侧模型、余额、额度、调用日志
P5 阶段	完成部署、观测、审计闭环	任务状态、日志、事件、指标、交付和审计
商业化阶段	套餐、团队、资源池和企业版能力	个人版、团队版、企业版与可运营体系

4. 建设范围与系统边界

4.1 建设范围

本项目建设范围包含以下部分：

Heicode 客户端：用户主体验、本地对话、任务输入、继续开发、执行反馈、交付结果和高危审批。
Heicode Manager：浏览器辅助控制台，负责账号、安全、客户端下载、资源绑定、权限分配、Agnet 部署、任务状态、余额、用量和审计。
Agnet 平台 / HeiCode Swarm：执行层，基于 AKS、Orchestrator、Redis 和 Agent Worker，负责任务执行、状态维护、日志、事件、指标和回调。
CodeGW 接入：模型网关、模型列表、余额、额度、用量和调用日志。
Secret Store / 密钥保管器：长期凭证托管、secret_ref、短期凭证派生、撤销、轮换和审计。
产品文档与运营材料：产品说明、用户指南、安全说明、计费说明、团队使用说明、FAQ、版本更新。

4.2 不在本阶段范围内

为避免项目边界发散，以下内容不作为当前阶段主线：

把 CodeGW 改造成普通用户直接使用的管理后台。
让普通用户直接进入 Azure Key Vault、AKS 或 Agnet 平台后台。
在客户端暴露模型供应商后台配置、渠道管理或价格配置。
在 Manager 中引入未明确设计的 tenant/project 作为当前扣费和团队控制主轴。
让 Markdown、日志、前端响应或 Git 中出现明文密钥。
在多 Agent 稳定性未验证前，将蜂群 DAG 作为默认生产路径。

4.3 系统边界

系统	用户理解	平台职责	普通用户是否直接进入
Heicode 客户端	本地主体验和审批入口	登录、对话、继续开发、查看反馈、审批高危操作	是
Heicode Manager	浏览器辅助控制台	资源绑定、部署 Agnet、查看状态、余额、日志、审计	是
Agnet 平台	AI 开发团队执行层	在 AKS 上运行子 Agnet，回传状态、事件、日志、指标	否
CodeGW	模型与用量底座	模型调用、余额、额度、调用日志	否
密钥保管器	凭证托管服务	保存长期密钥，按审批和权限生成短期访问能力	否

4.4 不可破坏的原则

Manager 是用户控制台与编排中枢，不是 CodeGW 的内嵌后台。
CodeGW 是内部模型网关和计费服务，不对普通用户开放后台。
Agnet 平台是执行层，不替代 Heicode 用户控制台。
客户端是主交互和高危审批入口，Manager 不替代客户端完成高危审批。
真实凭证进入密钥保管器，Manager DB 只保存 secret_ref。
子 Agnet 不保存长期密钥，只接收角色、资源元数据、AGENT.md、permission manifest 和受控访问方式。
Markdown 面向模型理解，permission manifest 面向系统强制执行。

5. 用户对象与典型场景

5.1 目标用户

用户	典型问题	Heicode 价值
独立开发者	有想法但缺完整工程团队	用 AI 团队完成从需求到上线
创业团队	人少、迭代快、交付压力大	编排产品、开发、测试、部署流程
企业创新团队	有资源和代码，但协作成本高	在既有 Git 和云资源边界内受控开发
技术负责人	担心权限、成本、质量和审计	统一资源授权、模型用量、日志和审计
运维负责人	担心生产操作风险	审批生产部署、查看日志、指标和回滚依据

5.2 典型场景一：从零生成 MVP

用户输入：

我想做一个小团队任务管理 SaaS，
需要登录、项目、任务、评论、通知和后台管理，
希望部署到 Azure。

平台执行：

生成需求摘要和功能清单。
生成产品文档和原型描述。
推荐 Git、云资源和模型预算。
推荐 Product、Frontend、Backend、Reviewer、Ops 等 Agnet 角色。
用户绑定 Git 仓库和 Azure 资源。
Manager 生成 permission manifest。
Agnet 执行开发、测试、修复和部署。
客户端审批生产部署。
用户在 Manager 查看状态、日志、用量和审计。

5.3 典型场景二：已有代码仓库继续开发

用户已有项目仓库，希望新增功能或修复问题。Heicode 读取用户授权的 Git、文档和 SK，按路径范围分配给不同角色：

Frontend Agnet 可读写前端目录。
Backend Agnet 可读写服务端目录。
Reviewer Agnet 可读全部变更但不直接部署。
Ops Agnet 仅在审批后访问部署资源。

最终输出包括代码分支、测试结果、变更说明、审计记录和可选部署结果。

5.4 典型场景三：企业受控 AI 开发

企业客户可将 Heicode 用作受控 AI 开发入口。团队负责人关心：

哪个用户发起任务。
哪些资源被授权给哪些角色。
是否访问生产资源。
是否经过审批。
消耗多少模型额度。
任务失败在哪里。
交付物是否可回放和审计。

Heicode 通过 Resource Grant、审批、日志、事件、指标和用量记录满足以上需求。

5.5 典型场景四：企业研发管理驾驶舱

在团队开发，特别是企业场景中，Heicode 不只要服务单个开发者，也要服务开发团队负责人、项目经理、技术负责人和企业管理者。团队领导需要看到的不是某一次 Agent 对话，而是整个项目和团队的开发态势。

企业研发管理场景中，负责人应能看到：

项目里程碑：当前版本、阶段目标、关键交付物、计划完成时间和延期风险。
总进度：项目整体完成比例、各模块完成比例、各 Agnet / 开发者任务完成比例。
开发者进度：每个开发者或人机协作角色正在做什么、已完成什么、阻塞在哪里。
Agnet 进度：每个子 Agnet 的当前任务、运行状态、成功率、失败原因和最近产物。
Bug 趋势：新增 Bug、已修复 Bug、重开 Bug、严重等级分布、模块分布和趋势变化。
Token 与成本消耗：按项目、成员、Agnet、任务、模型和日期统计的 token、费用和预算使用情况。
预计完成时间：基于剩余任务、历史吞吐、失败率、阻塞项和资源消耗估算 ETA。
风险预警：延期风险、预算超支风险、Bug 激增、审批阻塞、资源授权异常、生产部署失败。
质量指标：测试通过率、构建成功率、代码审查通过率、变更失败率和返工率。
审计链路：谁在什么时间让哪个人或 Agnet 使用了什么资源、执行了什么动作、是否经过审批。

这类能力的价值在于：Heicode 不只是“让 Agent 写代码”，而是把 AI 开发过程变成企业研发管理可以理解、可以度量、可以治理的系统。对企业负责人而言，Heicode 应该回答三个问题：

现在做到哪里了？
为什么卡住了？
按当前速度和风险，什么时候能交付？

因此，团队版和企业版应当内置研发管理驾驶舱，把项目进度、质量趋势、成本消耗、风险预警和审计证据统一呈现。

6. 产品方案

6.1 产品组成

6.1.1 Heicode 客户端

客户端是用户主体验，负责：

登录 Heicode。
输入产品想法、开发任务和追加需求。
展示 Heicode 提供的模型。
查看任务执行反馈和交付结果。
审批高危操作。
接收生产部署、数据库写入、大额模型消耗等风险提示。

客户端不负责：

配置模型供应商。
管理 CodeGW 渠道。
直接访问密钥保管器。
保存长期云密钥。

6.1.2 Heicode Manager

Manager 是浏览器辅助控制台，负责：

账号与安全。
客户端下载。
Git、文档、SK、云资源绑定。
资源授权和权限确认。
Agnet 部署与任务状态查看。
模型、余额、额度和调用日志展示。
审计日志、资源访问记录和执行事件查看。

Manager 不应该变成网页编码主体验，也不应该把底层配置表单直接暴露给普通用户。

6.1.3 Agnet 平台

Agnet 平台是执行层，负责：

在 AKS 上部署和运行子 Agnet。
执行需求、设计、开发、测试、修复、部署和维护任务。
按权限调用 SK 工具和外部能力。
维护 deployment、agent instance、任务状态、日志、事件和指标。
向 Manager 和客户端回传中间结果、失败原因、交付物和部署结果。

6.1.4 CodeGW

CodeGW 是模型网关和计费服务，负责：

模型调用。
模型可用性。
用户或 Token 维度余额。
额度和用量。
调用日志和失败日志。

普通用户只在 Heicode 中看到必要信息，不直接进入 CodeGW 后台。

6.1.5 密钥保管器

密钥保管器用于保存长期凭证，包括：

Git token。
SSH key。
云 access key。
数据库密码。
内部服务 token。

当前生产方向以 Azure Key Vault 为主要实现，长期演进可兼容 HashiCorp Vault 等 Secret Store。

6.2 用户主流程

登录 Heicode
-> 下载并登录客户端
-> 客户端输入产品想法
-> 查看需求摘要和任务草案
-> Manager 绑定 Git / 文档 / SK / 云资源
-> 平台自动发现资源并生成资源摘要
-> 生成子 Agnet 团队和角色方案
-> 用户确认角色权限和预算
-> 预览 permission manifest
-> 确认部署计划
-> Manager 请求 Agnet 平台部署
-> 客户端持续推进任务
-> Agnet 执行需求/设计/开发/测试/修复/部署
-> 客户端审批高危操作
-> Manager 展示日志、用量、审计和交付结果
-> 后续维护和升级

6.3 任务状态空间

用户在任务空间中应看到：

当前任务目标。
子 Agnet 数量和角色。
每个角色当前步骤。
任务图和依赖关系。
运行日志和失败原因。
模型用量和预算消耗。
资源访问记录。
审批记录。
中间产物和交付物。

用户可以执行：

暂停任务。
停止任务。
查看日志。
撤销资源授权。
追加需求。
发起修复。
继续迭代。

6.3.1 研发管理驾驶舱

面向团队负责人、技术负责人和企业管理者，Manager 需要提供独立的研发管理驾驶舱。它不是单个任务详情页，而是跨项目、跨成员、跨 Agnet、跨时间周期的管理视图。

建议驾驶舱分为七类视图：

视图	说明	关键指标
项目总览	展示项目整体状态和版本目标	总进度、当前里程碑、预计完成时间、延期风险
里程碑视图	展示阶段目标、关键任务和交付物	计划完成时间、实际完成时间、剩余任务、阻塞项
团队进度	展示开发者、人机协作角色和 Agnet 的任务状态	进行中、已完成、阻塞、待审查、待审批
Bug 趋势	展示质量变化和问题分布	新增 Bug、修复 Bug、重开 Bug、严重等级、模块分布
成本与 Token	展示模型与运行时资源消耗	token、费用、预算使用率、单任务成本、单 Agnet 成本
交付预测	基于剩余任务和历史吞吐估算完成时间	ETA、吞吐速度、失败率、返工率、风险等级
审计与风险	展示资源、审批和高危操作记录	资源访问、审批记录、失败部署、权限异常

驾驶舱的数据来源不应只依赖人工填写，而应来自系统事件：

任务图节点状态。
Git commit、分支、PR 和合并结果。
测试、构建、部署和回滚记录。
Bug、缺陷、失败任务和重试记录。
Agnet Runtime 日志、事件和 metrics。
CodeGW 模型调用和 token 用量。
Resource Grant、审批和资源访问审计。

对于预计完成时间，Heicode 可以先采用可解释的规则估算，而不是一开始追求复杂预测模型：

预计完成时间 =
剩余任务量 / 最近一段时间有效吞吐
+ 阻塞项修复时间
+ 失败重试和返工缓冲
+ 审批等待时间

后续可逐步引入更细的预测因子，例如不同模块复杂度、不同 Agnet 成功率、不同模型成本与通过率、团队历史 velocity、Bug 重开率和部署失败率。

6.4 Agnet 协作模式

Agnet 的协作模式可以理解为三代演进，而不是三种并列按钮。

代际	模式	核心特征	适用场景
第一代	链式（Chain）	任务按角色顺序流转，一个环节完成后进入下一个环节	强依赖、线性流程、简单工作流
第二代	Sub 模式	结合瀑布和敏捷优势，以子任务、闸门、审批和角色分工推进	团队任务协作、需要明确阶段交付
第三代	蜂群（Swarm）	多 Agent 按任务图并行或依赖调度，支持 capability 匹配和动态 handoff	大型改造、多模块并行、企业级受控执行

第一代链式 Agnet 更接近传统流水线：产品、架构、开发、测试、部署等角色按顺序承接任务。这种模式简单、稳定、容易解释，但吞吐有限，面对复杂项目时容易出现长链路等待和单点阻塞。

第二代 Sub 模式开始引入子任务和阶段闸门，把瀑布式的确定性和敏捷式的迭代性结合起来。它适合团队任务协作，可以让不同子任务独立推进，并在关键节点做审批、评审和交付确认。

第三代蜂群模式是当前 Heicode 更看重的方向。蜂群模式的关键不是“一个更聪明的 Agent”，而是“多个 Agent 像小型工程团队一样协同工作”。它通过任务图、能力匹配、依赖调度、状态回传、日志和检查点，把复杂任务拆成多个可并行、可恢复、可审计的执行单元。

蜂群模式并非没有弊端。它会带来更高的编排复杂度、更高的模型和基础设施成本，也会引入任务拆分质量、上下文一致性、结果合并、冲突处理和失败恢复等问题。因此，蜂群不应该被简单理解为“Agent 越多越好”，而应该被设计成可灰度、可限额、可观测、可回退的运行时能力。

但在当前模型能力快速爆发的阶段，蜂群模式有一个重要判断：能力较弱的模型，不见得不能通过多 Agent 协作对标一个能力强大的模型。强模型的优势来自单体模型内部的理解、推理和涌现能力；蜂群的优势则来自多个 Agent 在角色、任务、上下文、验证和反馈中的系统级涌现。只要任务拆分、角色边界、状态回传、验证机制和权限控制足够好，多个中等能力模型组成的 Agent 群体，其涌现能力不一定低于单一大模型的涌现能力。

这也是 Heicode 选择建设蜂群运行时的原因：未来的软件开发不只是在比较“哪个模型更强”，而是在比较“谁能把模型、角色、资源、权限、状态和反馈组织成一个持续交付系统”。蜂群模式让 Heicode 有机会在模型能力、成本结构和工程可控性之间形成自己的产品路径。

6.5 MVP 用户路径

MVP 最小可用路径建议为：

用户登录 Heicode。
下载并登录客户端。
输入一个产品想法。
绑定一个 Git 仓库。
绑定一个云账号或导入云资源。
选择推荐角色。
确认资源权限。
预览 permission manifest。
创建 Agnet 部署或占位任务。
在客户端持续推进子环节开发与测试。
查看任务状态、日志、审计和交付结果。

7. 技术架构方案

7.1 总体架构

┌──────────────────────────────────────────────────────────────┐
│                          用户                                │
│       产品想法 / 开发任务 / 追加需求 / 高危审批              │
└───────────────┬───────────────────────────────┬──────────────┘
                │                               │
                ▼                               ▼
┌──────────────────────────┐       ┌──────────────────────────┐
│     Heicode 客户端        │       │     Heicode Manager       │
│ 对话 / 反馈 / 审批 / 结果 │       │ 资源 / 权限 / 部署 / 审计 │
└───────────────┬──────────┘       └──────────────┬───────────┘
                │                                  │
                │                                  │ 服务端编排
                │                                  ▼
                │                   ┌──────────────────────────┐
                │                   │   Resource Binding /     │
                │                   │   Resource Grant /       │
                │                   │   permission manifest    │
                │                   └──────────────┬───────────┘
                │                                  │
                ▼                                  ▼
┌──────────────────────────┐       ┌──────────────────────────┐
│      CodeGW      │       │     Secret Store          │
│ 模型 / 余额 / 用量 / 日志 │       │ Key Vault / Vault / ref   │
└──────────────────────────┘       └──────────────┬───────────┘
                                                   │ secret_ref / 短期凭证
                                                   ▼
                                  ┌──────────────────────────┐
                                  │   Agnet 平台 / Swarm      │
                                  │ AKS / Orchestrator / Redis │
                                  │ Agent Worker / Logs       │
                                  └──────────────┬───────────┘
                                                 │
                                                 ▼
                                  ┌──────────────────────────┐
                                  │ Git / SK / 文档 / 云资源  │
                                  │ Repo / Tools / VM / DB    │
                                  └──────────────────────────┘

7.2 Manager 技术方案

Manager 负责把用户输入和授权资源整理成 Agnet 平台可执行的 work request。核心对象包括：

用户上下文：user.id、email、role、channelId。
任务上下文：用户输入、需求摘要、目标、约束。
资源上下文：Git、SK、项目文档、云账号、云资源。
角色上下文：Product、Architect、Frontend、Backend、Reviewer、Ops 等。
权限上下文：Resource Binding、Resource Grant、allowed actions、constraints。
密钥上下文：secret_ref、TTL、审批结果。
计费上下文：CodeGW user / token / group / quota 映射。
运行时上下文：Agnet role、model profile、instance count、callback URL。

Manager 需要提供的能力：

登录态校验并复用 Heicode/Agnet 认证体系。
资源绑定、列表、详情、授权、撤销接口。
仅返回元数据和 secret_ref，不返回明文密钥。
生成 AGENT.md / resource context。
生成 permission manifest。
调用 Agnet Runtime Bridge。
接收 Agnet 回调、事件、日志和指标。
查询 CodeGW 模型、余额、额度和调用日志。
提供任务状态、审计和用量视图。

7.3 Agnet 平台技术方案

HeiCode Swarm 采用 Kubernetes 多 Agent 执行架构，核心组件包括：

组件	职责
Orchestrator	接收任务、维护任务图、调度 Agent、处理回调、状态和日志
Redis / 状态服务	保存任务状态、事件、检查点和队列
Agent Worker	执行代码修改、测试、验证、文档生成、Git 工作流
Runtime Bridge	面向 Manager 暴露 swarm/deployment/health/callback/approval 等接口
Metrics / Logs / Tracing	采集任务运行指标、日志、事件和调用归因

当前 Swarm 已具备：

单 Agent MVP：领取任务、调用模型、提交 Git 结果并 push 分支。
Runtime Bridge：/api/swarms、/api/agnet/deployments、/api/agnet/health。
callback、approval、tasks、logs、metrics 相关能力。
多 Agent DAG 灰度路径：ENABLE_SUBTASK_HANDOFF=true。
capability 匹配、依赖调度、一层动态 handoff。

7.4 CodeGW 接入方案

Manager 不直接复制 CodeGW 后台能力，而是通过服务凭据调用 CodeGW，对普通用户展示必要信息：

可用模型。
当前余额。
当前额度。
今日消耗。
调用日志。
失败日志。
模型可用状态。

Manager 不展示：

渠道管理。
模型供应商后台配置。
价格配置。
CodeGW 管理员用户管理。
CodeGW 原生管理后台入口。

推荐映射：

Heicode/Agnet 字段	CodeGW 映射	用途
`user.id` / JWT `sub`	CodeGW user ref	标识调用归属用户
`channelId`	CodeGW channel/user/group 绑定	关联模型渠道、额度或扣费策略
绑定 Git 仓库	request metadata	审计某次开发任务来源
预算或用量限制	token quota 或 group policy	限制任务消耗额度

7.5 客户端技术方案

macOS 客户端当前位于 heicode-macos-release 仓库，发布版本已到 v0.4.18。客户端在产品中承担：

Heicode 登录。
模型列表和可用性展示。
对话与任务输入。
继续开发和结果查看。
高危操作审批。
交付反馈展示。

近期客户端修复重点包括：

代理环境下模型列表、额度和用量加载问题。
聊天 / 模型探活对齐服务端 V2 鉴权。
登录时补全 Manager 网关地址。
不持久化 accessToken、refreshToken、managerLoginUrl 等敏感信息。

8. 安全、凭证与审计方案

8.1 安全目标

Heicode 是 SaaS 产品，不能把凭证管理转嫁给用户，也不能让密钥散落在 Git、Markdown、日志或子 Agnet 长期状态中。安全目标包括：

用户授权资源，平台托管凭证。
Heicode 服务端数据库只保存元数据和 secret_ref。
长期密钥进入密钥保管器。
子 Agnet 只拿短期、最小权限、可审计凭证。
高危操作必须由客户端审批。
所有资源、权限、模型、日志和审批进入审计链路。

8.2 凭证分类

凭证	示例	存放位置
Git 凭证	GitHub token、Gitea token、SSH key	密钥保管器
云凭证	Azure、AWS、GCP access key	密钥保管器
数据库凭证	DB password、connection secret	密钥保管器
CodeGW 服务凭据	内部服务 token	服务环境或密钥保管器
短期凭证	临时云 token、临时 Git token	运行时注入，TTL 到期失效

8.3 Secret Broker 流程

用户绑定资源
-> Heicode 接收授权结果
-> Heicode Secret Broker 写入 Azure Key Vault / Vault
-> Secret Store 返回或形成 secret_ref
-> Heicode DB 保存 secret_ref
-> 前端只展示脱敏引用和状态

接口、日志、错误信息、审计摘要都不得包含明文密钥。

8.4 Resource Binding 与 Resource Grant

资源绑定不是保存一串密钥，而是创建面向登录用户、绑定 Git/SK/云资源和子 Agnet 角色的授权基础。

Resource Binding 记录：

资源类型。
用户可见名称。
外部资源定位。
可见元数据。
权限范围。
使用限制。
secret_ref。
状态。
审计字段。

Resource Grant 记录：

授权归属。
被授权资源。
子 Agnet 角色。
Agent 标识。
允许动作。
限制条件。
过期时间。
创建与撤销审计。

8.5 高危操作审批

高危操作包括：

生产环境部署。
云资源创建、删除、扩缩容。
数据库迁移或写入。
访问生产密钥。
大额模型预算消耗。

审批必须记录：

审批人。
审批时间。
操作类型。
资源范围。
风险等级。
TTL。
对应 deployment 或任务。

8.6 审计目标

审计系统必须能够回答：

谁
在什么时候
为了哪个任务
让哪个子 Agnet
使用了哪个资源
执行了什么操作
是否经过审批
消耗了多少模型额度
产生了什么结果

9. 计费、资源与商业化设计

9.1 计费单位

平台采用 X 作为统一计费单位。当前文档预计：

1X = 标准基础模型连续工作额度（约等于 10 美金）

最终价格以实际购买页面或合同约定为准。

9.2 套餐设计

套餐类型	金额档位	服务倍率	主要能力
基础版	14 / 20 / 120 美元	5X	以 Qwen 系列等基础模型为主，支持连续性工作
高级版	600 / 800 / 1000 美元	20X	以 GPT-5 系列作为基础模型，支持更高质量连续性工作

9.3 个人版与团队版

个人版适合单人使用，所有模型调用和服务消耗从同一扣费账号扣除，最多可部署 5 个 Agnet。
团队版适合多人协作，团队成员共享同一扣费账号，最多可部署 8 个 Agnet。

9.4 Agnet 计费

Agnet 使用会产生两类消耗：

消耗类型	扣费方式
Agnet 平台资源消耗	按实际使用 `EU` 扣分
Agnet 调用模型费用	从主扣费账号中扣除

9.5 蜂群模式成本特征

蜂群模式通常比单 Agent 更贵，原因包括：

多个 Agent 同时消耗模型 token。
多个 Agent 同时占用基础设施资源。
需要协调层、状态层、日志层和监控层。

但在复杂任务中，蜂群用更高单次成本换取：

更高吞吐。
更高并发。
更高可控性。
更高可追踪性。
更适合企业审计和协同。

9.6 商业化分层建议

层级	适合用户	能力建议
个人版	独立开发者	基础模型、少量 Agnet、共享资源池、基础日志
团队版	小团队 / 创业团队	更多 Agnet、团队共享扣费、任务协作、审计和审批
企业版	企业创新团队 / 技术部门	隔离资源池、企业权限、私有部署选项、合规审计、SLA

10. 当前实现基础

10.1 本地项目结构

路径	说明
`heicode-mananger/`	Heicode Manager、网关和管理控制台服务端
`HeiCode-Swarm/`	基于 Kubernetes 的多 Agent 编程执行系统
`heicode-macos-release/`	Heicode macOS 客户端发布仓库
`heicodedocs/`	从文档站抓取并转换后的 Heicode 产品文档
`项目书.md`	当前项目书

10.2 Manager 基础

Manager 现有文档已明确：

Heicode 产品定位与系统边界。
P0–P5 实施计划。
登录接口对接。
CodeGW 扣费映射。
Azure Key Vault 凭证托管方向。
Agnet 平台请求契约。
产品资料包、用户旅程、安全说明和平台说明。

当前重点是把文档中收敛的 Resource Binding、Resource Grant、Secret Broker、Agnet payload 和审计字段落实到代码主线。

10.3 Swarm 基础

HeiCode Swarm 当前状态：

单 Agent MVP 已跑通。
Runtime Bridge 已提供 /api/swarms、/api/agnet/deployments、/api/agnet/health。
已补充 callback、approval、tasks、logs、metrics 能力。
多 Agent DAG 主流程已实现，可通过 ENABLE_SUBTASK_HANDOFF=true 灰度开启。
线上部署在 Azure AKS 的 swarm-system 命名空间。
当前发布方式为“源码 ConfigMap + rollout restart”。
生产环境需要配置 AGNET_RUNTIME_SERVICE_TOKEN、AGNET_CALLBACK_SERVICE_TOKEN、AGNET_CALLBACK_SIGNING_SECRET。

10.4 客户端基础

macOS 客户端发布仓库显示：

最新提交为 v0.4.18 发布。
近期修复了代理环境下模型列表、额度/用量加载慢或失败的问题。
修复了聊天 / 模型探活与服务端 V2 鉴权对齐问题。
修复了设备配对打网关地址的问题。
强化了敏感登录信息不持久化的边界。

10.5 文档基础

heicodedocs/ 已包含 Heicode 文档站全部 Heicode 分组内容，包括：

介绍。
登录平台和使用平台指南。
安全与凭证管理说明。
团队使用。
Agnet 构建。
计费。
隐私及法规。
版本更新。

这些文档可作为产品、客服、销售、培训和官网内容的初始素材。

11. 实施路线图

11.1 P0：边界收敛

目标：团队只围绕一套产品和架构边界协作。

任务：

以 heicode.md 作为当前产品与架构共识。
不再恢复旧 Agnet API 草案、旧 M1-M5 计划和旧 UI 命名作为主线。
明确 Manager / Agnet / CodeGW / Secret Store 边界。
明确客户端和 Manager 的职责分工。

验收：

文档中没有多套互相冲突的 Manager、Agnet、CodeGW 计划。
新需求先落到文档共识，再进入实现。

11.2 P1：资源模型与授权

目标：把“Git 来源”升级为统一资源绑定模型。

任务：

建立 Resource Binding。
建立 Resource Grant。
支持 Git、SK、项目文档、云账号、单项云资源。
提供资源绑定、授权、撤销和 manifest 生成。
所有接口只返回元数据和 secret_ref。

验收：

Manager 能表达“某登录用户把某个绑定资源授予某个子 Agnet 角色使用”。
撤销 Resource Grant 后，新的 permission manifest 不再包含该授权。
数据库不保存明文密钥。

11.3 P2：Secret Broker 与密钥保管器

目标：建立 SaaS 多用户凭证托管能力。

任务：

实现 Secret Broker。
接入 Azure Key Vault 或 Vault。
完成写入、轮换、撤销、禁用和审计。
完成日志脱敏、前端响应过滤、Markdown 过滤。

验收：

Git token、云密钥、SSH key、数据库密码不会进入 Git、Markdown、前端响应或普通日志。
用户可以授权和撤销资源。

11.4 P3：Agnet 平台 AKS 身份接入

目标：让子 Agnet 在 AKS 上按最小权限访问授权资源。

任务：

支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
支持 Vault Kubernetes Auth 或等价 Workload Identity。
支持按 user / resource binding / role 生成密钥访问策略。
支持普通资源受控注入和高危资源审批后短期凭证注入。

验收：

子 Agnet 不保存长期密钥。
撤销 Resource Grant 后，子 Agnet 不能继续访问对应资源。
高危资源访问有审计记录。

11.5 P4：CodeGW 解耦与用户侧展示

目标：让 CodeGW 回到模型网关与计费底座的位置。

任务：

Manager 通过服务凭据调用 CodeGW。
展示普通用户需要的模型、余额、额度、用量、调用日志。
隐藏渠道管理、价格配置、模型供应商后台配置和管理员能力。
建立 user.id / channelId 与 CodeGW user / token / group / quota 的映射。

验收：

普通用户只进入 Heicode，不进入 CodeGW 后台。
Manager 能展示模型与用量信息。
CodeGW 升级不要求 Manager 跟随改造核心后台逻辑。

11.6 P5：部署、观测与审计闭环

目标：跑通用户想法到子 Agnet 部署、执行、观测和审计的闭环。

任务：

Manager 生成 AGENT.md、resource context 和 permission manifest。
调用 Agnet Runtime Bridge。
Agnet 平台回传 deployment、agent instance、状态、事件、日志和指标。
Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
对高危权限增加审批、撤销和运行中失效机制。

验收：

用户能看到每个子 Agnet 的角色、模型、资源权限、运行状态和失败原因。
审计能回答谁在什么时候让哪个子 Agnet 使用了什么资源。
Markdown 只作为上下文，permission manifest 才是系统执行依据。

12. 验收指标

12.1 产品验收

指标	验收标准
登录	用户能登录 Manager 和客户端，身份一致
想法输入	用户能输入目标并生成需求摘要和任务草案
资源绑定	用户能绑定 Git、文档、SK、云资源中的至少一类资源
权限确认	用户能查看角色权限摘要和 manifest 预览
Agnet 部署	Manager 能创建部署或占位任务，并获得状态反馈
执行反馈	用户能看到任务状态、日志、失败原因和交付结果
高危审批	生产部署、数据库写入等操作必须在客户端审批
用量展示	用户能看到模型、余额、额度和调用日志

12.2 安全验收

指标	验收标准
数据库	只保存元数据和 `secret_ref`，不保存明文密钥
前端	不显示 token、password、private key、access key
日志	普通日志不包含明文密钥
Markdown	AGENT.md / resource context 不包含明文密钥
子 Agnet	不保存长期凭证
高危审批	每次审批有审批人、时间、资源、TTL、任务和风险等级
撤销	Resource Grant 撤销后，新 manifest 不再包含对应授权

12.3 运行时验收

指标	验收标准
健康检查	`/api/agnet/health` 可用
创建任务	`/api/swarms` 或兼容入口能创建任务
状态回传	deployment、tasks、logs、metrics 可查询
鉴权	Runtime token 与调用方 Bearer token 对齐
失败处理	任务失败有错误结构、状态和日志
灰度	多 Agent DAG 通过开关启用，不影响单 Agent 主路径

12.4 交付验收

指标	验收标准
代码分支	Agent 结果能提交到独立分支或形成可审查产物
测试结果	至少回传测试命令、结果和失败原因
交付物	形成变更说明、部署说明或 release note
审计快照	每次部署保留资源、权限、模型和上下文快照

12.5 学术化与工程化评价指标

为了让 Heicode 具备“项目可落地、研究可评价、产品可迭代”的闭环，建议将验收指标进一步拆成四组：Agentic SDLC 指标、DORA 交付指标、安全治理指标和供应链可信指标。

12.5.1 Agentic SDLC 指标

指标	含义	采集方式
任务完成率	Agnet 在限定资源和预算内完成任务的比例	deployment / task 终态统计
人工介入率	需要人类修正、接管或重试的任务比例	approval、escalation、manual override 事件
Agent 接受率	用户接受 Agent 生成结果的比例	交付确认、PR 合并、用户反馈
验证通过率	Agent 变更通过测试、lint、构建或部署检查的比例	CI、测试日志、执行结果
上下文命中率	Agent 是否使用了正确的仓库、文档、资源和 SK	resource access log 与任务上下文比对
失败可诊断率	失败任务是否有明确错误结构、日志和下一步建议	error package、logs、events 完整性
总进度准确率	系统展示的项目完成比例与实际交付状态的偏差	里程碑、任务图、交付物和验收结果比对
ETA 偏差率	预计完成时间与实际完成时间的偏差	预测 ETA 与任务/里程碑完成时间比对
Bug 趋势覆盖率	Bug 新增、修复、重开和严重等级是否被持续统计	issue、测试失败、缺陷记录和修复记录
成本归因完整率	token 和费用是否能归因到项目、成员、Agnet、任务和模型	CodeGW 调用日志、runtime usage、task metadata
管理视图延迟	团队驾驶舱数据从事件发生到可见的延迟	event ingestion time 与 dashboard display time

12.5.2 DORA 软件交付指标

指标	Heicode 对应口径
变更交付时间（Lead Time for Changes）	从任务创建 / commit 到可部署或已部署的时间
部署频率（Deployment Frequency）	单用户、单团队或单项目在周期内完成部署的次数
失败部署恢复时间（Failed Deployment Recovery Time）	部署失败后恢复到可用状态的时间
变更失败率（Change Failure Rate）	Agent 或团队部署导致故障、回滚或热修复的比例
部署返工率（Deployment Rework Rate）	因生产问题触发非计划部署或修复部署的比例

12.5.3 安全治理指标

指标	验收口径
高危审批覆盖率	生产部署、数据库写入、云资源变更、大额预算消耗必须 100% 有审批
最小权限命中率	Resource Grant 中 allowed actions 不得超出 Resource Binding 范围
明文密钥暴露次数	Git、Markdown、日志、前端响应中明文密钥暴露次数为 0
撤销生效率	授权撤销后，新 manifest 和新运行时访问立即移除对应权限
审计完整率	每次关键操作包含 user、agent、resource、action、time、approval、result

12.5.4 供应链可信指标

指标	验收口径
交付物 provenance	每次交付记录来源仓库、commit、构建参数、执行环境和 Agent 角色
构建可追溯	构建产物能追溯到源代码、依赖、构建器和任务上下文
依赖可审计	依赖变更有记录，关键依赖升级有测试和审查结果
Agent 变更可回放	能根据任务、日志、diff、测试和审批还原 Agent 执行链路
产物完整性	发布包、镜像或部署 artifact 有版本、摘要和签名/校验信息

13. 运营与交付方案

13.1 发布策略

建议采用以下发布策略：

客户端、Manager、Swarm Runtime 保持版本记录。
每次发布至少回归登录、模型拉取、对话请求。
Agnet Runtime 发布先在测试环境验证契约测试。
多 Agent DAG 先灰度启用，再逐步扩大范围。
生产高危操作发布必须保留审批和回滚记录。

13.2 运维监控

需要持续监控：

Manager API 状态。
客户端登录和模型探活成功率。
CodeGW 余额、调用失败率和延迟。
Agnet Runtime 健康检查。
Orchestrator 日志和 Redis 状态。
Agent Worker 运行状态。
任务失败率、平均耗时、token 消耗和成本。
Key Vault / Secret Store 访问失败率。

13.3 用户运营

初期可围绕三类用户运营：

独立开发者：突出“从想法到 MVP”。
创业团队：突出“少人力完成迭代”。
企业创新团队：突出“权限、审计、审批和资源边界内使用 AI 开发”。

运营材料可以复用：

产品说明文档。
5 分钟演示脚本。
PPT 文案。
登录和使用指南。
安全与凭证管理说明。
团队使用 FAQ。

13.4 客户支持

支持体系应覆盖：

登录失败。
客户端下载和版本问题。
模型列表 / 余额加载失败。
Git 授权失败。
云资源绑定失败。
Agnet 部署失败。
高危审批未触发。
任务执行超时。
部署失败和回滚。

14. 风险分析与应对

风险	表现	影响	应对
产品边界发散	Manager 变成 CodeGW 后台或网页 IDE	用户体验混乱，实施成本升高	坚持客户端主体验、Manager 辅助控制台、CodeGW 内部底座
资源模型未落地	Git source、SK、云资源字段各自为政	无法统一授权和审计	优先实现 Resource Binding / Grant
密钥泄露	token 进入日志、Markdown、前端或 Git	严重安全事故	Secret Broker、脱敏、扫描、短期凭证和审批
Agnet 联调不稳定	部署创建、状态回传、日志回调不一致	闭环无法演示	先契约测试，再灰度接入，保留占位任务
多 Agent 成本过高	多 Agent 并行导致 token 与资源消耗高	商业模式承压	共享池、VIP 池、模型分层、按需拉起、检查点恢复
用户理解门槛高	用户不理解资源、权限、manifest	转化率低	默认展示角色权限摘要，高级能力折叠
高危审批遗漏	生产部署或数据库写入未审批	安全与合规风险	客户端强制审批，后端校验 approval_id 和范围
发布方式不成熟	Swarm 仍用源码 ConfigMap 发布	生产变更风险	逐步推进镜像化发布和回滚策略

15. 组织分工建议

角色	职责
产品负责人	产品定位、用户旅程、套餐、文案、验收口径
Manager 后端	登录、资源模型、Secret Broker、CodeGW 接入、Agnet 契约、审计
Manager 前端	资源绑定、权限确认、任务状态、用量、审计、客户端下载
客户端负责人	登录、对话、任务推进、高危审批、结果展示
Swarm / Agnet 负责人	Orchestrator、Agent Worker、Runtime Bridge、DAG、日志和指标
安全负责人	Key Vault / Vault、密钥脱敏、短期凭证、审批策略、审计
运维负责人	AKS、Redis、发布、监控、告警、回滚
测试负责人	登录、资源绑定、密钥安全、Agnet 联调、端到端验收

16. 附录：术语、文档与仓库索引

16.1 术语

术语	说明
Heicode	面向全流程智能开发的产品总称
Heicode 客户端	用户主体验，承担对话、继续开发、审批和结果查看
Heicode Manager	浏览器辅助控制台，承担资源、权限、部署、状态、用量和审计
Agnet	平台生成的 AI 开发角色
HeiCode Swarm	基于 Kubernetes 的多 Agent 编程执行系统
CodeGW	模型网关和计费底座
Secret Store / 密钥保管器	保存长期凭证的安全底座
Resource Binding	用户绑定的资源元数据和密钥引用
Resource Grant	某资源授予某用户、任务或子 Agnet 角色的授权关系
permission manifest	面向系统强制执行的结构化权限清单
AGENT.md / resource context	面向模型理解的角色和资源上下文
SK	技能仓库或技能包，可供 Agnet 在执行过程中调用

16.2 仓库索引

仓库 / 目录	用途
`heicode-mananger/`	Manager、网关、产品资料、集成文档
`HeiCode-Swarm/`	Orchestrator、Agent Worker、K8s、运行时文档
`heicode-macos-release/`	macOS 客户端发布与运行时代码
`heicodedocs/`	从 PandaWiki 文档站同步的 Heicode 产品文档

16.3 关键文档索引

Manager 主线：

heicode-mananger/docs/heicode.md
heicode-mananger/docs/plan.md
heicode-mananger/docs/heicode-runtime-auth-codegw-secret-design.md
heicode-mananger/docs/product-package/
heicode-mananger/docs/integration/agnet-platform-request-contract.md

Swarm 主线：

HeiCode-Swarm/README.md
HeiCode-Swarm/实现状态总览.md
HeiCode-Swarm/蜂群对接文档.md
HeiCode-Swarm/蜂群模式完整说明文档.md
HeiCode-Swarm/部署和使用文档.md

产品文档站同步：

heicodedocs/介绍.md
heicodedocs/登录平台和使用平台指南.md
heicodedocs/安全与凭证管理说明.md
heicodedocs/Agnet构建/
heicodedocs/团队使用/
heicodedocs/计费/
heicodedocs/隐私及法规/

16.4 对外统一表述

用户侧叫 Heicode，不叫 CodeGW 后台。
Heicode 客户端 是用户主体验。
Heicode Manager 是浏览器辅助控制台。
用户侧叫 密钥保管器，技术实现可说明为 Azure Key Vault 或 Vault。
用户侧叫 资源绑定，不要只叫 Git 来源。
客户端不出现模型提供方、旧服务入口、第三方路由入口等内部概念。
CodeGW 是内部模型网关与计费服务，不作为普通用户入口。
Agnet 平台是执行层，不替代 Heicode 的用户控制台。

17. 参考文献与外部依据

本项目书在内部仓库材料之外，参考了以下外部研究、标准和产业资料，用于支撑 Heicode 的学术方向、工程指标、安全治理和落地验收。

17.1 Agentic Software Engineering 与 Agentic SDLC

Agentic AI in the Software Development Lifecycle: Architecture, Empirical Evidence, and the Reshaping of Software Engineering：提出 Agentic Software Engineering 与 Agentic SDLC 的整体框架，强调软件工程 AI 正从代码补全走向仓库级、功能级和任务级的委托式执行。
SWE-bench: Can Language Models Resolve Real-world Github Issues?：以真实 GitHub issue 和 pull request 构建评测，证明真实软件工程需要跨文件修改、执行环境、测试验证和复杂推理。
SWE-bench GitHub：提供 SWE-bench 数据集、评测工具和 Verified 子集信息，可作为 Heicode 后续评测体系参考。

17.2 多 Agent 软件开发研究

MetaGPT: Meta Programming for a Multi-Agent Collaborative Framework：将 SOP 编码进多 Agent 协作流程，使用 Product Manager、Architect、Engineer 等角色生成结构化产物。
AGILECODER: Dynamic Collaborative Agents for Software Development based on Agile Methodology：将敏捷方法引入多 Agent 软件开发，使用 Product Manager、Scrum Master、Developer、Tester 等角色和 sprint 流程。
HyperAgent: Generalist Software Engineering Agents to Solve Coding Tasks at Scale：通过 Planner、Navigator、Code Editor、Executor 等角色覆盖软件工程任务的分析、定位、编辑和验证。

17.3 AI 风险、安全与治理

NIST AI Risk Management Framework 1.0：提出 Govern、Map、Measure、Manage 四类 AI 风险管理功能，适合作为 Heicode AI 治理和责任边界参考。
NIST AI RMF Generative AI Profile：针对生成式 AI 风险补充治理、评估、人机配置和安全管理要求。
OWASP Top 10 for LLM Applications 2025：其中 Excessive Agency 与 Heicode 的 Resource Grant、高危审批、最小权限设计直接相关。
NIST SP 800-207 Zero Trust Architecture：强调资源级保护、连续验证和最小权限，支撑 Heicode 对 Agent 访问资源的零信任设计。

17.4 软件交付、供应链与落地指标

DORA Software Delivery Performance Metrics：提供变更交付时间、部署频率、失败恢复时间、变更失败率和部署返工率等工程交付指标。
SLSA Specification：提供软件供应链安全分级、provenance 和 artifact 可验证性要求，可作为 Heicode 交付物可信与审计设计参考。
SLSA Provenance：说明制品 provenance 如何记录构建平台、输入、依赖和产物，可映射到 Agent 生成代码、构建包和部署结果的可追溯设计。

结语

Heicode 项目的目标不是“做一个能写代码的 AI 工具”，而是把软件交付中的产品、代码、权限、模型、资源、部署和维护组织为一条安全、可审计、可持续推进的生命周期流程。

项目当前已经具备 Manager 文档与代码基础、Swarm 运行时基础、macOS 客户端发布基础和产品文档站内容基础。下一阶段应优先围绕资源模型、密钥托管、Agnet 联调、用量展示和审计闭环推进，把现有能力从多个仓库和文档中的分散能力收敛为一个可演示、可交付、可商业化的 Heicode 平台。

@chenchen @lizhengwei @qinhao @xiaohei @xiongwei @zhanggangyong @zhaosonghao