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

编排提案契约（orchestration_plan）

本文定义「模型提案、平台裁决」模式下的最小编排对象，供 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": []
    }
  ],
  "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，并通过事件流持续反馈执行状态