docs: add agnet platform request contract

2026-05-02 23:42:51 +08:00
parent 57a86ce060
commit ab71d5b72b
2 changed files with 636 additions and 1 deletions
@@ -0,0 +1,634 @@
+# Manager → Agnet 平台接口参数文档
+
+**版本**: v0.1（P1 最小可验证契约）  
+**方向**: Heicode Manager 主动请求 Agnet 平台；Agnet 平台返回部署、日志、监控与审计状态。  
+**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志。  
+**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`；不得传明文密码、Token、私钥、连接串或云访问密钥。
+
+> 本文档描述 Manager 对 Agnet 平台的出站集成契约。当前仓库中 `/api/agnet/*` 是 Manager 侧最小控制面/模拟端点，用于校验同一套 payload 结构；生产接入时，Manager 应将下列请求发送到 Agnet 平台网关。
+
+---
+
+## 1. 接入约定
+
+### 1.1 Base URL
+
+由部署环境配置，不写入仓库。例如：
+
+```text
+AGNET_PLATFORM_BASE_URL=https://agnet-platform.example.com
+```
+
+### 1.2 通用 Header
+
+| Header | 必填 | 说明 |
+|---|---:|---|
+| `Authorization: Bearer <manager-service-token>` | 是 | Manager 服务身份令牌，由 Secret Store/运行环境注入。 |
+| `Content-Type: application/json` | POST/PUT 是 | JSON 请求体。 |
+| `X-Tenant-Id: <tenant_id>` | 是 | 租户边界；必须等于 body/query 中 tenant_id。 |
+| `X-Project-Id: <project_id>` | 建议 | 项目边界，便于平台鉴权与审计。 |
+| `X-Correlation-Id: <uuid>` | 是 | Manager 生成，全链路追踪。 |
+| `X-Request-Id: <uuid>` | 建议 | 单次 HTTP 请求追踪 ID，可与 correlation_id 不同。 |
+| `Idempotency-Key: <uuid>` | 创建类接口建议 | 避免重试造成重复部署。 |
+
+### 1.3 通用响应包裹
+
+成功：
+
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+失败：
+
+```json
+{
+  "success": false,
+  "message": "human readable message",
+  "error": {
+    "code": "POLICY_REJECTED",
+    "message": "human readable message",
+    "request_id": "req_xxx"
+  }
+}
+```
+
+建议错误码：
+
+| code | 场景 |
+|---|---|
+| `POLICY_REJECTED` | 缺必填字段、权限策略不满足、风险等级非法。 |
+| `BUDGET_EXCEEDED` | 超过 token/金额/时长预算。 |
+| `MODEL_NOT_ALLOWED` | agent 默认模型不在允许列表内。 |
+| `FORBIDDEN_CROSS_TENANT` | Header 与 body/query 租户不一致。 |
+| `RESOURCE_GRANT_INVALID` | Resource Grant 字段缺失、跨租户/跨项目/角色不匹配。 |
+| `RESOURCE_GRANT_SECRET_REF_REQUIRED` | 凭据型资源缺少 `secret_ref`。 |
+| `RESOURCE_GRANT_SECRET_REJECTED` | 请求中出现明文密钥字段。 |
+| `SK_SOURCE_UNRESOLVABLE` | SK 来源不可解析。 |
+| `DEPLOYMENT_CONFLICT` | 部署不存在、状态冲突或重复提交。 |
+
+---
+
+## 2. 创建子 Agent 部署
+
+### 2.1 Endpoint
+
+```http
+POST /api/agnet/deployments
+```
+
+### 2.2 请求体
+
+```json
+{
+  "orchestration_plan": {
+    "intent_id": "intent_20260502_001",
+    "template_hint": "manager-resource-binding",
+    "objective": "为项目 project-a 启动 builder 子 Agent，允许其读取 SK 并在限定路径内提交代码",
+    "risk_level": "low",
+    "budget": {
+      "max_tokens": 100000,
+      "max_cost_usd": 30,
+      "max_duration_sec": 7200
+    },
+    "constraints": {
+      "allowed_model_ids": ["gpt-5.4-mini", "gpt-5.4"]
+    },
+    "metadata": {
+      "tenant_id": "tenant-a",
+      "project_id": "project-a",
+      "correlation_id": "corr_20260502_001"
+    },
+    "agents": [
+      {
+        "role_template": "builder",
+        "goal": "按 Manager 下发的任务在允许资源内完成实现、验证并回传状态",
+        "default_model_id": "gpt-5.4-mini",
+        "sk_sources": [
+          {
+            "type": "git",
+            "mime": "text/markdown",
+            "repo_ref": {
+              "connection_id": "conn_sk_repo_001",
+              "repo_url": "https://example.com/org/sk-repo.git",
+              "ref": "main",
+              "paths": ["skills/heicode/**", "AGENTS.md"]
+            }
+          }
+        ],
+        "runtime_execution": {
+          "profile_id": "aks-codex-standard",
+          "cloud_principal_refs": ["principal://tenant-a/agnet-runtime"],
+          "network_policy_ref": "netpol://tenant-a/restricted-egress"
+        },
+        "sk_access_policy": {
+          "policy_ref": "sk-policy://tenant-a/default-readonly",
+          "deny_skill_ids": ["dangerous-shell"],
+          "inherit_deployment_defaults": true
+        },
+        "resource_grants": [
+          {
+            "grant_id": "grant_git_repo_001",
+            "resource_id": "res_git_repo_001",
+            "resource_type": "git",
+            "tenant_id": "tenant-a",
+            "project_id": "project-a",
+            "target_role": "builder",
+            "target_agent_ref": "agent-builder-1",
+            "permission_scope": ["repo:read", "repo:write:current-branch"],
+            "constraints": {
+              "ref": "main",
+              "allowed_paths": "heicode/**,docs/**",
+              "forbid_branch_create": "true"
+            },
+            "metadata": {
+              "provider": "gitee",
+              "repo_url": "https://example.com/org/repo.git"
+            },
+            "status": "active",
+            "secret_ref": "vault://tenant-a/git/res_git_repo_001",
+            "audit": {
+              "created_by": "manager",
+              "approval_id": "approval_001"
+            }
+          },
+          {
+            "grant_id": "grant_doc_001",
+            "resource_id": "res_project_doc_001",
+            "resource_type": "project_doc",
+            "tenant_id": "tenant-a",
+            "project_id": "project-a",
+            "target_role": "builder",
+            "target_agent_ref": "agent-builder-1",
+            "permission_scope": ["doc:read"],
+            "constraints": {
+              "doc_paths": "docs/heicode.md,docs/plan.md"
+            },
+            "metadata": {
+              "doc_ref": "project-doc://project-a/docs-mainline"
+            },
+            "status": "active",
+            "secret_ref": "",
+            "audit": {
+              "created_by": "manager"
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 2.3 字段说明
+
+#### orchestration_plan
+
+| 字段 | 类型 | 必填 | 约束/说明 |
+|---|---|---:|---|
+| `intent_id` | string | 是 | Manager 侧意图 ID，用于幂等、审计和追踪。 |
+| `template_hint` | string | 是 | Agnet 平台选择编排模板的提示，如 `manager-resource-binding`。 |
+| `objective` | string | 是 | 本次部署目标，应是自然语言但不能含密钥。 |
+| `risk_level` | enum | 是 | `low` / `medium` / `high`。高风险应触发审批或只读模式。 |
+| `budget.max_tokens` | int | 是 | 当前策略上限建议不超过 `500000`。 |
+| `budget.max_cost_usd` | number | 是 | 当前策略上限建议不超过 `200`。 |
+| `budget.max_duration_sec` | int | 是 | 当前策略上限建议不超过 `86400`。 |
+| `constraints.allowed_model_ids` | string[] | 否 | agent 的 `default_model_id` 如填写，必须在此列表内。 |
+| `metadata.tenant_id` | string | 是 | 必须与 `X-Tenant-Id` 一致。 |
+| `metadata.project_id` | string | 是 | 项目隔离边界。 |
+| `metadata.correlation_id` | string | 是 | 全链路追踪 ID。 |
+| `agents` | array | 是 | 至少 1 个子 Agent。 |
+
+#### agents[]
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `role_template` | string | 是 | 平台角色模板，如 `builder`/`reviewer`/`operator`。 |
+| `goal` | string | 是 | 此 agent 的任务目标。 |
+| `default_model_id` | string | 否 | 默认模型；若设置需满足 allowed_model_ids。 |
+| `sk_sources` | array | 否 | SK 来源，平台应解析为只读快照。 |
+| `runtime_execution` | object | 否 | 运行环境绑定；任一字段存在时 `profile_id` 必填。 |
+| `sk_access_policy` | object | 否 | SK 权限策略。若 `deny_skill_ids` 非空，需 `policy_ref` 或继承默认策略。 |
+| `resource_grants` | array | 否 | Manager 下发给子 Agent 的最小权限资源授权。 |
+
+#### sk_sources[]
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `type` | enum | 否 | 空值表示不启用；支持 `git`、`upload`。 |
+| `artifact_id` | string | upload 必填 | 上传型 SK 包 ID。 |
+| `mime` | string | 否 | 内容类型，如 `text/markdown`。 |
+| `repo_ref.connection_id` | string | git 建议 | Git 连接资源 ID。 |
+| `repo_ref.repo_url` | string | git 建议 | 仓库 URL；不得带用户名密码。 |
+| `repo_ref.ref` | string | git 必填 | 分支/标签/commit。 |
+| `repo_ref.paths` | string[] | git 必填 | 允许读取的路径。 |
+
+#### runtime_execution
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `profile_id` | string | 条件必填 | Agnet 平台运行规格，如 AKS profile。 |
+| `cloud_principal_refs` | string[] | 否 | 运行身份引用，不是明文凭据。 |
+| `network_policy_ref` | string | 否 | 网络策略引用，用于限制出站/入站。 |
+
+#### resource_grants[]
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `grant_id` | string | 是 | 授权记录 ID。 |
+| `resource_id` | string | 是 | Manager 资源 ID。 |
+| `resource_type` | enum | 是 | `git` / `sk` / `project_doc` / `cloud_account` / `cloud_resource`。 |
+| `tenant_id` | string | 是 | 必须等于 orchestration metadata。 |
+| `project_id` | string | 是 | 必须等于 orchestration metadata。 |
+| `target_role` | string | 是 | 必须等于当前 agent 的 `role_template`。 |
+| `target_agent_ref` | string | 是 | Manager 侧对子 Agent 的逻辑引用。 |
+| `permission_scope` | string[] | 是 | 最小权限列表，如 `repo:read`、`doc:read`。 |
+| `constraints` | object<string,string> | 否 | 路径、分支、区域、超时等限制；不得含密钥字段。 |
+| `metadata` | object<string,string> | 否 | 资源展示/审计元数据；不得含密钥字段。 |
+| `status` | enum | 是 | `pending` / `active` / `disabled` / `revoked`。 |
+| `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 |
+| `audit` | object<string,string> | 否 | 审计上下文；不得含密钥字段。 |
+
+### 2.4 成功响应
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "status": "accepted",
+    "agent_instances": [
+      {
+        "instance_id": "agi_abc123",
+        "role": "builder",
+        "phase": "pending"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 3. 部署状态与控制接口
+
+### 3.1 查询部署列表
+
+```http
+GET /api/agnet/deployments?tenant_id=tenant-a&project_id=project-a
+```
+
+返回：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "deployment_id": "dep_abc123",
+        "status": "accepted",
+        "phase": "pending",
+        "created_at": "2026-05-02T00:00:00Z",
+        "updated_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+### 3.2 查询单个部署
+
+```http
+GET /api/agnet/deployments/{deployment_id}
+```
+
+返回应包含部署状态、phase、agent_instances、最近错误、资源授权摘要和预算消耗摘要。Agnet 平台返回时必须对 `secret_ref` 以外的凭据信息做脱敏；原则上不返回任何明文凭据。
+
+### 3.3 停止部署
+
+```http
+POST /api/agnet/deployments/{deployment_id}/stop
+```
+
+请求体可为空；如需原因可扩展：
+
+```json
+{
+  "reason": "user_requested",
+  "requested_by": "manager"
+}
+```
+
+成功：
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "status": "stopped"
+  }
+}
+```
+
+---
+
+## 4. 日志接口（Manager 拉取 Agnet 平台）
+
+### 4.1 获取部署日志
+
+```http
+GET /api/agnet/deployments/{deployment_id}/logs?agent_instance_id=agi_abc123&stream=stdout&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
+```
+
+Query：
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `agent_instance_id` | 否 | 不传则返回该 deployment 下全部实例日志。 |
+| `stream` | 否 | `stdout` / `stderr` / `system` / `audit`，默认全部。 |
+| `since` | 否 | RFC3339 时间，增量拉取起点。 |
+| `limit` | 否 | 默认 200，建议最大 1000。 |
+| `cursor` | 否 | 分页游标。 |
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "log_id": "log_001",
+        "deployment_id": "dep_abc123",
+        "agent_instance_id": "agi_abc123",
+        "stream": "stdout",
+        "level": "info",
+        "message": "task started",
+        "redacted": true,
+        "occurred_at": "2026-05-02T00:00:01Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+日志要求：
+
+- Agnet 平台必须在返回前完成密钥脱敏。
+- `message` 不得包含密码、Token、私钥、连接串、云访问密钥。
+- Manager 只保存必要摘要和审计索引；长日志建议落对象存储并设置保留期。
+
+### 4.2 实时日志流（可选）
+
+```http
+GET /api/agnet/deployments/{deployment_id}/logs/stream?agent_instance_id=agi_abc123
+Accept: text/event-stream
+```
+
+SSE event 示例：
+
+```text
+event: log
+data: {"log_id":"log_002","level":"info","message":"step completed","occurred_at":"2026-05-02T00:00:02Z"}
+```
+
+---
+
+## 5. 监控接口（Manager 拉取 Agnet 平台）
+
+### 5.1 项目监控快照
+
+```http
+GET /api/agnet/projects/{project_id}/dashboard-snapshot?tenant_id=tenant-a&window=1h
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "project_id": "project-a",
+    "active_instances": 3,
+    "phase_distribution": {
+      "pending": 1,
+      "running": 2,
+      "stopped": 0,
+      "failed": 0
+    },
+    "failure_rate_1h": 0.02,
+    "avg_task_duration": 185.3,
+    "budget": {
+      "tokens_used": 32000,
+      "cost_usd": 4.21,
+      "duration_sec": 930
+    },
+    "resource_usage": {
+      "cpu_millicores": 1200,
+      "memory_mb": 2048,
+      "network_rx_bytes": 102400,
+      "network_tx_bytes": 204800
+    },
+    "updated_at": "2026-05-02T00:05:00Z"
+  }
+}
+```
+
+### 5.2 单部署监控快照（建议平台实现）
+
+```http
+GET /api/agnet/deployments/{deployment_id}/metrics?window=15m&step=60s
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "window": "15m",
+    "series": [
+      {
+        "metric": "tokens_used",
+        "unit": "count",
+        "points": [["2026-05-02T00:00:00Z", 1200]]
+      },
+      {
+        "metric": "cpu_millicores",
+        "unit": "millicore",
+        "points": [["2026-05-02T00:00:00Z", 500]]
+      }
+    ]
+  }
+}
+```
+
+建议指标：`tokens_used`、`cost_usd`、`duration_sec`、`cpu_millicores`、`memory_mb`、`restart_count`、`tool_call_count`、`error_count`、`queue_latency_ms`。
+
+---
+
+## 6. 事件与审计接口
+
+### 6.1 部署事件
+
+```http
+GET /api/agnet/deployments/{deployment_id}/events?since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "event_id": "evt_001",
+        "event": "deployment.accepted",
+        "schema_version": 1,
+        "tenant_id": "tenant-a",
+        "project_id": "project-a",
+        "deployment_id": "dep_abc123",
+        "correlation_id": "corr_20260502_001",
+        "occurred_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+常用事件名：
+
+| event | 说明 |
+|---|---|
+| `deployment.accepted` | 平台接受部署请求。 |
+| `instance.phase_changed` | 子 Agent phase 变化。 |
+| `sk_snapshot_refreshed` | SK 快照解析/刷新完成。 |
+| `resource_grant.attached` | 资源授权已绑定到实例。 |
+| `resource_grant.revoked` | 授权被撤销或禁用。 |
+| `budget.threshold_reached` | 预算阈值触发。 |
+| `deployment.failed` | 部署失败。 |
+
+### 6.2 审计日志
+
+```http
+GET /api/agnet/audit-logs?tenant_id=tenant-a&project_id=project-a&actor=agnet_control_plane&action=deployment.accepted&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "audit_id": "aud_001",
+        "actor": "agnet_control_plane",
+        "action": "deployment.accepted",
+        "resource": "dep_abc123",
+        "tenant_id": "tenant-a",
+        "project_id": "project-a",
+        "request_id": "req_001",
+        "correlation_id": "corr_20260502_001",
+        "result": "ok",
+        "occurred_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+---
+
+## 7. SK 快照接口
+
+### 7.1 触发解析/刷新
+
+```http
+POST /api/agnet/sk-snapshots/resolve
+```
+
+请求：
+
+```json
+{
+  "deployment_id": "dep_abc123"
+}
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "items": [
+      {
+        "snapshot_id": "sks_001",
+        "deployment_id": "dep_abc123",
+        "tenant_id": "tenant-a",
+        "project_id": "project-a",
+        "source_type": "git",
+        "source_ref": "main:skills/heicode/**@sha_xxx",
+        "resolved_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+### 7.2 查询部署 SK 快照
+
+```http
+GET /api/agnet/deployments/{deployment_id}/sk-snapshots
+```
+
+---
+
+## 8. 安全校验清单
+
+Manager 发给 Agnet 平台前必须执行：
+
+1. `tenant_id`、`project_id`、`target_role` 与部署计划一致。
+2. 凭据型资源只传 `secret_ref`，不传明文凭据。
+3. `metadata`、`constraints`、`audit` 的 key 中不得出现 `password`、`token`、`secret`、`private_key`、`access_key`、`credential` 等敏感词。
+4. `repo_url` 不得包含用户名、密码或访问 Token。
+5. `permission_scope` 使用最小权限，生产写操作需审批记录或平台代理执行。
+6. 高风险操作（生产部署、云资源修改、删除、扩容）应设置 `risk_level=high` 并由 Agnet 平台二次审批。
+7. 所有日志/事件/审计返回给 Manager 前必须脱敏。
+
+---
+
+## 9. Manager 侧当前实现映射
+
+当前代码中可用于对齐/验证 payload 的 Manager 侧端点：
+
+| Manager 路由 | 用途 |
+|---|---|
+| `POST /api/agnet/deployments` | 校验并接受 orchestration_plan。 |
+| `GET /api/agnet/deployments` | 按 tenant/project 查询部署。 |
+| `GET /api/agnet/deployments/:deployment_id` | 查询部署详情。 |
+| `POST /api/agnet/deployments/:deployment_id/stop` | 停止部署。 |
+| `GET /api/agnet/deployments/:deployment_id/events` | 查询事件。 |
+| `POST /api/agnet/sk-snapshots/resolve` | 解析 SK 快照。 |
+| `GET /api/agnet/deployments/:deployment_id/sk-snapshots` | 查询 SK 快照。 |
+| `GET /api/agnet/projects/:project_id/dashboard-snapshot` | 项目监控快照。 |
+| `GET /api/agnet/audit-logs` | 审计日志。 |
+
+生产对接时，Manager 应把相同契约的请求发送给 Agnet 平台；本地 Manager 端点仅作为最小验证与控制面占位，不代表所有日志/监控平台能力已完整实现。