# Agent 能力与调度 Schema（Capability / Registry / Routing）

> 状态：**DRAFT / 待对齐 Infra & Scheduling Team**。
>
> 依据：`heicode-mananger/docs/heicode.md §五`、`docs/integration/heicode-am-contract.md §2`。配套：[`runtime-contract.md`](./runtime-contract.md)、[`security-boundary.md`](./security-boundary.md)。

## 1. 现状

- 当前能力调度为 **swarm 私有实现**：Agent 以 `AGENT_CAPABILITIES` 注册到编排器（Redis 注册表），编排器按「`required_capabilities ⊆ agent.capabilities` + 剩余容量」派发。
- **尚未接入统一 agent registry / capability center / quota / tenant / region·GPU 调度 / provider routing / model policy**。这些归 Infra/Scheduling，未在本仓实现（避免 Runtime Scheduling 双实现）。

## 2. 已实现的能力模型（本仓）

### 2.1 Agent 注册（`AgentMetadata`）
```jsonc
{ "agent_id": "...", "status": "idle|busy|handoff-pending|failed",
  "capabilities": ["python","testing", ...], "current_task_id": "...|null",
  "last_heartbeat": 0.0 }
```
另：register/heartbeat 上报 `available_slots`（剩余容量），编排器据此避免向满载 Agent 派发。

### 2.2 任务侧能力需求
任务携带 `agent_role` 与 `required_capabilities`；派发用 `can_agent_run_task`（`required ⊆ capabilities`，空需求视为通用可执行）。

### 2.3 能力别名（`handoff_logic.CAPABILITY_ALIASES`）
`code_generation` / `python` / `general` 等扩展为本地等价能力集合，用于移交决策与匹配宽松化。

### 2.4 角色（role）
- Manager/产品口径角色（`heicode.md §五`）：`product`、`frontend`、`backend`、`reviewer`、`ops`。
- 本仓规划回退默认角色：`implementation`、`testing`、`documentation`（`agent_role` 字段，注入 `specialist_role`）。

## 3. 角色 ↔ 资源 ↔ env（对齐 AM）

资源授权（Resource Grant，Manager 侧）按角色绑定资源，HM 解析为固定 env 名注入 Agent（`heicode-am-contract §2`）：

| 资源类型 | provider | 非密 env | 密钥 env（经 secret_ref） |
|---|---|---|---|
| git | github/gitea/gitlab | `GIT_PROVIDER` `GIT_REPO_URL` `GIT_DEFAULT_BRANCH` | `GIT_TOKEN` |
| database | mysql / postgres | `MYSQL_*` / `POSTGRES_*`（host/port/db/user） | `MYSQL_PASSWORD` / `POSTGRES_PASSWORD` |
| storage | azure blob | `AZURE_BLOB_ACCOUNT_NAME` `AZURE_BLOB_CONTAINER` | `AZURE_BLOB_ACCOUNT_KEY` |

角色/指令经 `AGENT_ROLE_NAME` + `AGENT_INSTRUCTION_TEXT` 注入（AM 约定）。

## 4. 目标统一调度 Schema（待 Infra 定义）

| 维度 | 字段（建议） | 状态 |
|---|---|---|
| Registry | `agent_id`、`capabilities`、`role`、`framework`、`version`、`health` | 🟡 本仓有私有注册表，未接统一中心 |
| Capability center | 能力字典、能力版本、能力↔工具映射 | 🔴 未接入 |
| Quota | `max_concurrent`、`token_quota`、`cost_quota`（按 user/channelId） | 🟡 仅 Agent 侧 `MAX_CONCURRENT_TASKS`/容量 |
| Tenant isolation | —（按标准用 user/channelId，不引入 tenant） | ⛔ 不在本仓 |
| Region / GPU scheduling | `region`、`gpu_class`、`node_pool` | 🔴 未接入（AKS/Infra） |
| Provider routing | `provider`、`model_policy`、`fallback` | 🔴 未接入（NewAPI/网关侧） |
| Model policy | `model_ref`、`profile`、`budget` | 🟡 Agent 用 `OPENAI_MODEL`；统一 policy 未接 |

## 5. 缺口

- 🔴 统一 agent registry / capability center / provider routing / region·GPU 调度：未实现，归 Infra/Scheduling。
- 🟡 配额仅 Agent 并发/容量级；无 user/channelId 维度配额中心。
- ⛔ tenant 维度：按标准不引入。
- ⚠️ 风险：若 Infra 落地统一调度，需收敛本仓私有派发，避免 Runtime Scheduling 双实现。

## 6. 待对齐对象

Infra & Scheduling Team：统一 registry/capability center 字段、quota（按 user/channelId）、region·GPU·provider routing、model policy，以及本仓私有派发与统一调度的收敛路径。