heicode/docs/integration/orchestration-plan-contract.md

编排提案契约（orchestration_plan）

Deprecated: 本文是早期编排提案草案。2026-05-02 之后，正式计划需要补齐 Resource Grant、Secret Broker、Secret Store、AKS 运行身份和平台代理语义；主参考见 ../saas-manager-agnet-architecture-plan.md。

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

1. 决策边界

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

2. 最小对象

{
  "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": [],
      "runtime_execution": {
        "profile_id": "exec_profile_vm_pool_ci",
        "cloud_principal_refs": ["cp_az_mi_build"],
        "network_policy_ref": "net_project_default"
      },
      "sk_access_policy": {
        "policy_ref": "tenant_sk_policy_default",
        "deny_skill_ids": ["sk_cross_env_admin"],
        "inherit_deployment_defaults": true
      }
    }
  ],
  "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 来源列表
agents[].runtime_execution	否	须在转为部署请求时保留：子 agent 云上执行绑定（VM/池、云 principal、网络策略等），与 agnet-platform-api-design.md §5.0 一致
agents[].sk_access_policy	否	须在转为部署请求时保留：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 不超策略上限
6. 运行时边界：若存在 runtime_execution，其引用须为本租户已授权的执行档案 / 云 principal（否则 RUNTIME_BINDING_INVALID）
7. SK 策略：若存在 sk_access_policy，合并后须一致且可执行（否则 SK_POLICY_REJECTED）

5. 典型拒绝码

code	含义
POLICY_REJECTED	平台策略拒绝执行
MODEL_NOT_ALLOWED	模型未授权
SK_SOURCE_UNRESOLVABLE	SK 源无法解析或无权限读取
RUNTIME_BINDING_INVALID	云上 / 运行时绑定无效或未授权
SK_POLICY_REJECTED	SK 允许 / 拒绝策略冲突
BUDGET_EXCEEDED	预算超限
FORBIDDEN_CROSS_TENANT	跨租户访问拒绝
DEPLOYMENT_CONFLICT	幂等冲突或状态冲突

6. 对接建议

• orchestration_plan 建议由 Manager 无损映射为 Agnet POST /deployments 标准 payload；runtime_execution / sk_access_policy 不得在进入部署链路时丢弃，否则子 agent 无法获得用户在 Manager 配置的权限与 SK 边界
• 拒绝时应返回 error.code + request_id + correlation_id
• 接受后返回 deployment_id，并通过事件流持续反馈执行状态