# 编排提案契约（`orchestration_plan`）

本文定义「模型提案、平台裁决」模式下的最小编排对象，供 Heicode / Manager / Agnet 三方对齐。

## 1. 决策边界

- **模型（经 SK 引导）**：产出编排提案 `orchestration_plan`
- **Agnet 平台**：执行策略裁决（权限、预算、模型授权、租户隔离），并决定是否执行
- **Heicode Manager**：承载入口与状态展示，透传提案并记录 `correlation_id`

## 2. 最小对象

```json
{
  "intent_id": "intent_20260430_001",
  "template_hint": "agile_min",
  "objective": "实现并验证用户登录链路",
  "risk_level": "medium",
  "budget": {
    "max_tokens": 120000,
    "max_cost_usd": 8.0,
    "max_duration_sec": 3600
  },
  "agents": [
    {
      "role_template": "AG-PO",
      "goal": "拆解验收标准并输出任务分配",
      "default_model_id": "mdl_claude_sonnet",
      "sk_sources": [
        {
          "type": "git",
          "repo_ref": {
            "connection_id": "gitconn_1",
            "repo_url": "https://example.com/org/sk-repo.git",
            "ref": "main",
            "paths": ["agile/po-guideline.md"]
          }
        }
      ]
    },
    {
      "role_template": "AG-DEV",
      "goal": "按拆解清单完成实现与自测",
      "default_model_id": "mdl_claude_sonnet",
      "sk_sources": []
    }
  ],
  "constraints": {
    "allowed_model_ids": ["mdl_claude_sonnet", "mdl_claude_haiku"],
    "forbidden_actions": ["cross_tenant_read", "credential_write"]
  },
  "metadata": {
    "tenant_id": "ten_001",
    "project_id": "prj_auth",
    "correlation_id": "mgr_cor_abc"
  }
}
```

## 3. 字段说明（最小集）

| 字段 | 必填 | 说明 |
|------|------|------|
| `intent_id` | 是 | 业务意图 ID，幂等与审计用 |
| `template_hint` | 是 | 期望模板（如 `agile_min` / `waterfall_min`） |
| `objective` | 是 | 任务目标摘要 |
| `risk_level` | 是 | `low` / `medium` / `high` |
| `budget.*` | 是 | token、成本、时长预算上限 |
| `agents[]` | 是 | 子 agent 提案列表 |
| `agents[].role_template` | 是 | 角色模板 |
| `agents[].goal` | 是 | 该角色目标 |
| `agents[].default_model_id` | 否 | 建议模型；最终由平台策略裁决 |
| `agents[].sk_sources` | 否 | SK 来源列表 |
| `constraints.allowed_model_ids` | 否 | 允许模型白名单 |
| `metadata.tenant_id` | 是 | 顶层隔离键 |
| `metadata.project_id` | 是 | 项目标识 |
| `metadata.correlation_id` | 是 | 全链路追踪键 |

## 4. 裁决规则（平台侧）

Agnet 在执行前必须做下列校验：

1. 租户与项目一致性：`tenant_id` / `project_id` 与令牌声明匹配
2. 权限校验：调用主体具备部署与读取权限
3. 模型授权：`default_model_id` 在组织与项目策略允许范围内
4. SK 边界：`sk_sources` 可解析、可读、无越权路径
5. 预算约束：`max_tokens` / `max_cost_usd` / `max_duration_sec` 不超策略上限

## 5. 典型拒绝码

| code | 含义 |
|------|------|
| `POLICY_REJECTED` | 平台策略拒绝执行 |
| `MODEL_NOT_ALLOWED` | 模型未授权 |
| `SK_SOURCE_UNRESOLVABLE` | SK 源无法解析或无权限读取 |
| `BUDGET_EXCEEDED` | 预算超限 |
| `FORBIDDEN_CROSS_TENANT` | 跨租户访问拒绝 |
| `DEPLOYMENT_CONFLICT` | 幂等冲突或状态冲突 |

## 6. 对接建议

- `orchestration_plan` 建议由 Manager 转换成 Agnet `POST /deployments` 标准 payload
- 拒绝时应返回 `error.code` + `request_id` + `correlation_id`
- 接受后返回 `deployment_id`，并通过事件流持续反馈执行状态