docs: complete Agnet platform contract

2026-05-03 18:05:45 +08:00
parent aba1ce28df
commit 6a3e918787
1 changed files with 251 additions and 5 deletions
@@ -1,12 +1,35 @@
 # Manager → Agnet 平台接口参数文档

-**版本**: v0.1（P1 最小可验证契约）  
+**版本**: v0.2（P1/P5 联调契约）
+**生效日期**: 2026-05-03
+**状态**: 联调准备；当前仓库提供 Manager 侧最小验证端点，生产 Agnet 平台部署尚未在本文档中宣称完成。
 **方向**: Heicode Manager 主动请求 Agnet 平台；Agnet 平台返回部署、日志、监控与审计状态。
-**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志。  
-**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`；不得传明文密码、Token、私钥、连接串或云访问密钥。
+**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志，以及 Agnet 辅助 NewAPI 重建/部署的参数约定。
+**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`/环境变量名；不得传明文密码、Token、私钥、连接串或云访问密钥。

 > 本文档描述 Manager 对 Agnet 平台的出站集成契约。当前仓库中 `/api/agnet/*` 是 Manager 侧最小控制面/模拟端点，用于校验同一套 payload 结构；生产接入时，Manager 应将下列请求发送到 Agnet 平台网关。

+## 0. 概述
+
+本文档按登录接口文档的对接方式组织：先定义接入信息，再逐个接口给出请求、响应、错误和安全约束。接口分组如下：
+
+| 接口 | 用途 | 当前性质 |
+|---|---|---|
+| `POST /api/agnet/deployments` | 创建子 Agent/运维任务部署，含 NewAPI 重建/部署场景 | 必需 |
+| `GET /api/agnet/deployments` | 查询部署列表 | 必需 |
+| `GET /api/agnet/deployments/{deployment_id}` | 查询单个部署详情 | 必需 |
+| `POST /api/agnet/deployments/{deployment_id}/stop` | 停止部署或取消排队任务 | 必需 |
+| `GET /api/agnet/deployments/{deployment_id}/logs` | 拉取部署日志 | 必需 |
+| `GET /api/agnet/deployments/{deployment_id}/logs/stream` | 实时日志 SSE | 可选 |
+| `GET /api/agnet/projects/{project_id}/dashboard-snapshot` | 项目监控快照 | 必需 |
+| `GET /api/agnet/deployments/{deployment_id}/metrics` | 单部署指标序列 | 建议 |
+| `GET /api/agnet/deployments/{deployment_id}/events` | 部署事件 | 必需 |
+| `GET /api/agnet/audit-logs` | 审计日志 | 必需 |
+| `POST /api/agnet/sk-snapshots/resolve` | 触发 SK 快照解析 | 必需 |
+| `GET /api/agnet/deployments/{deployment_id}/sk-snapshots` | 查询 SK 快照 | 必需 |
+
+> 不在本文档范围：真实 Secret Store 写入、生产 SSH 登录、云账号授权回调、NewAPI 管理后台开放。生产部署动作只有实际执行并通过日志/监控/审计验证后，才能在报告中标记为“已部署”。
+
 ---

 ## 1. 接入约定
@@ -19,6 +42,19 @@
 AGNET_PLATFORM_BASE_URL=https://agnet-platform.example.com
 ```

+联调环境建议使用独立域名或内网网关，示例不得包含真实凭据：
+
+```text
+AGNET_PLATFORM_BASE_URL=https://staging-agnet.example.com
+MANAGER_SERVICE_TOKEN_SECRET_REF=vault://tenant-a/manager/agnet-service-token
+```
+
+完整路径示例：
+
+```http
+POST https://agnet-platform.example.com/api/agnet/deployments
+```
+
 ### 1.2 通用 Header

 | Header | 必填 | 说明 |
@@ -69,6 +105,24 @@ AGNET_PLATFORM_BASE_URL=https://agnet-platform.example.com
 | `RESOURCE_GRANT_SECRET_REJECTED` | 请求中出现明文密钥字段。 |
 | `SK_SOURCE_UNRESOLVABLE` | SK 来源不可解析。 |
 | `DEPLOYMENT_CONFLICT` | 部署不存在、状态冲突或重复提交。 |
+| `NOT_FOUND` | deployment、agent instance、snapshot 或审计资源不存在。 |
+| `CURSOR_EXPIRED` | 分页游标过期或不属于当前查询条件。 |
+| `RATE_LIMITED` | 平台限流；响应头建议包含 `Retry-After`。 |
+| `INTERNAL_ERROR` | 平台内部错误；Manager 应记录 request_id 并重试或提示稍后处理。 |
+
+### 1.4 通用错误处理
+
+| HTTP | business code | Manager 处理建议 |
+|---:|---|---|
+| 400 | `POLICY_REJECTED` / `RESOURCE_GRANT_INVALID` | 标记部署失败，展示校验原因，不自动重试。 |
+| 401 | `UNAUTHORIZED` | 检查 Manager 服务令牌的 `secret_ref`/环境注入，不把令牌写入日志。 |
+| 403 | `FORBIDDEN_CROSS_TENANT` / `MODEL_NOT_ALLOWED` | 阻断本次部署，写审计事件。 |
+| 404 | `NOT_FOUND` | 对查询类接口返回空态；对控制类接口提示资源不存在。 |
+| 409 | `DEPLOYMENT_CONFLICT` | 使用 `Idempotency-Key` 查询既有结果，避免重复创建。 |
+| 410 | `CURSOR_EXPIRED` | 丢弃 cursor，使用 `since` 重新拉取。 |
+| 422 | `RESOURCE_GRANT_SECRET_REF_REQUIRED` / `RESOURCE_GRANT_SECRET_REJECTED` | 要求 Manager 重新生成只含 `secret_ref` 的 payload。 |
+| 429 | `RATE_LIMITED` | 按 `Retry-After` 退避重试。 |
+| 500/503 | `INTERNAL_ERROR` | 指数退避重试；超过阈值后转人工排查。 |

 ---

@@ -252,7 +306,107 @@ POST /api/agnet/deployments
 | `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 |
 | `audit` | object<string,string> | 否 | 审计上下文；不得含密钥字段。 |

-### 2.4 成功响应
+### 2.4 典型场景：Agnet 辅助 NewAPI 重建/部署
+
+当 Manager 需要让 Agnet 平台协助重建或部署 NewAPI 时，仍使用 `POST /api/agnet/deployments`，但必须把任务表达为受控运维部署，不得把 VM、PostgreSQL、Redis、NewAPI key 等真实凭据写入请求体。
+
+请求体示例：
+
+```json
+{
+  "orchestration_plan": {
+    "intent_id": "intent_newapi_rebuild_20260503_001",
+    "template_hint": "newapi-rebuild-deploy",
+    "objective": "在批准窗口内重建 NewAPI 服务并回传健康检查、日志与资源使用摘要",
+    "risk_level": "high",
+    "budget": {
+      "max_tokens": 80000,
+      "max_cost_usd": 20,
+      "max_duration_sec": 3600
+    },
+    "constraints": {
+      "allowed_model_ids": ["gpt-5.4", "gpt-5.4-mini"],
+      "requires_approval": "true",
+      "rollback_required": "true",
+      "healthcheck_url_ref": "env://NEWAPI_HEALTHCHECK_URL"
+    },
+    "metadata": {
+      "tenant_id": "tenant-a",
+      "project_id": "newapi-prod",
+      "correlation_id": "corr_newapi_20260503_001",
+      "service": "new-api",
+      "environment": "production"
+    },
+    "agents": [
+      {
+        "role_template": "operator",
+        "goal": "按 runbook 执行构建、服务重启、健康检查和失败回滚；只通过 secret_ref/env 获取凭据",
+        "default_model_id": "gpt-5.4",
+        "runtime_execution": {
+          "profile_id": "aks-codex-ops",
+          "cloud_principal_refs": ["principal://tenant-a/agnet-ops"],
+          "network_policy_ref": "netpol://tenant-a/ops-egress"
+        },
+        "resource_grants": [
+          {
+            "grant_id": "grant_newapi_vm_ops",
+            "resource_id": "res_newapi_vm",
+            "resource_type": "cloud_resource",
+            "tenant_id": "tenant-a",
+            "project_id": "newapi-prod",
+            "target_role": "operator",
+            "target_agent_ref": "agent-operator-1",
+            "permission_scope": ["vm:ssh:approved-window", "service:restart", "log:read", "healthcheck:read"],
+            "constraints": {
+              "approval_id": "approval_newapi_001",
+              "window": "2026-05-03T10:00:00Z/2026-05-03T11:00:00Z",
+              "rollback_command_ref": "runbook://newapi/rollback"
+            },
+            "metadata": {
+              "host_ref": "env://NEWAPI_VM_HOST",
+              "service_name": "new-api"
+            },
+            "status": "active",
+            "secret_ref": "vault://tenant-a/cloud/newapi-vm-ops",
+            "audit": {
+              "created_by": "manager",
+              "approval_id": "approval_newapi_001"
+            }
+          },
+          {
+            "grant_id": "grant_newapi_runtime_env",
+            "resource_id": "res_newapi_runtime_env",
+            "resource_type": "cloud_resource",
+            "tenant_id": "tenant-a",
+            "project_id": "newapi-prod",
+            "target_role": "operator",
+            "target_agent_ref": "agent-operator-1",
+            "permission_scope": ["env:read:runtime", "secret:read:scoped"],
+            "constraints": {
+              "allowed_env_refs": "DATABASE_DSN,REDIS_URL,NEWAPI_SERVICE_TOKEN",
+              "plaintext_export_forbidden": "true"
+            },
+            "metadata": {
+              "secret_provider": "vault",
+              "scope": "newapi-runtime"
+            },
+            "status": "active",
+            "secret_ref": "vault://tenant-a/newapi/runtime-env",
+            "audit": {
+              "created_by": "manager",
+              "approval_id": "approval_newapi_001"
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Agnet 平台返回的部署详情、日志、监控和审计中应至少能证明：构建版本/commit、服务重启结果、健康检查结果、资源使用情况、失败回滚状态。未执行真实 SSH/生产动作时，只能返回 `phase=planned` 或 `phase=pending_approval`。
+
+### 2.5 成功响应

 ```json
 {
@@ -336,6 +490,17 @@ POST /api/agnet/deployments/{deployment_id}/stop
 }
 ```

+错误与幂等：
+
+| HTTP | business code | 说明 |
+|---:|---|---|
+| 200 | - | 已停止的部署重复停止也可返回 200，并保持 `status=stopped`。 |
+| 404 | `NOT_FOUND` | 部署不存在或不属于当前租户/项目。 |
+| 409 | `DEPLOYMENT_CONFLICT` | 部署已进入不可停止的终态，如 `completed` 且无运行实例。 |
+| 422 | `POLICY_REJECTED` | 高风险停止缺少审批记录或 reason 不合法。 |
+
+若停止请求触发异步回收，平台可返回 `status=stopping`；Manager 应继续通过事件、日志和监控接口确认最终状态。
+
 ---

 ## 4. 日志接口（Manager 拉取 Agnet 平台）
@@ -400,6 +565,23 @@ event: log
 data: {"log_id":"log_002","level":"info","message":"step completed","occurred_at":"2026-05-02T00:00:02Z"}
 ```

+SSE 事件类型：
+
+| event | 说明 |
+|---|---|
+| `log` | 普通日志行，必须已脱敏。 |
+| `heartbeat` | 保活事件，建议 15-30 秒一次。 |
+| `error` | 流式读取错误；不包含敏感上下文。 |
+| `done` | 部署进入终态或服务端主动结束流。 |
+
+错误处理：
+
+| HTTP | business code | Manager 处理建议 |
+|---:|---|---|
+| 401/403 | `UNAUTHORIZED` / `FORBIDDEN_CROSS_TENANT` | 立即断开流并记录审计。 |
+| 404 | `NOT_FOUND` | 停止订阅并刷新部署详情。 |
+| 429 | `RATE_LIMITED` | 退避后重连，保留 `Last-Event-Id`。 |
+
 ---

 ## 5. 监控接口（Manager 拉取 Agnet 平台）
@@ -599,6 +781,50 @@ POST /api/agnet/sk-snapshots/resolve
 GET /api/agnet/deployments/{deployment_id}/sk-snapshots
 ```

+Query：
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `tenant_id` | 建议 | 与 `X-Tenant-Id` 一致；平台可从 Header 推导。 |
+| `project_id` | 建议 | 项目边界；平台可从 deployment 推导。 |
+| `source_type` | 否 | `git` / `upload`，用于筛选。 |
+| `limit` | 否 | 默认 100，最大 500。 |
+| `cursor` | 否 | 分页游标。 |
+
+成功响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "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",
+        "artifact_ref": "artifact://tenant-a/sk/sks_001",
+        "checksum": "sha256:example-redacted",
+        "status": "ready",
+        "resolved_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+错误处理：
+
+| HTTP | business code | 说明 |
+|---:|---|---|
+| 404 | `NOT_FOUND` | deployment 不存在或不属于当前租户/项目。 |
+| 410 | `CURSOR_EXPIRED` | cursor 过期，使用不带 cursor 的查询重拉。 |
+| 422 | `SK_SOURCE_UNRESOLVABLE` | 快照来源不可解析，详情在事件/日志中查看。 |
+
 ---

 ## 8. 安全校验清单
@@ -613,6 +839,26 @@ Manager 发给 Agnet 平台前必须执行：
 6. 高风险操作（生产部署、云资源修改、删除、扩容）应设置 `risk_level=high` 并由 Agnet 平台二次审批。
 7. 所有日志/事件/审计返回给 Manager 前必须脱敏。

+### 8.1 字段级约束速查
+
+| 对象/接口 | 必填最小集合 | 禁止内容 |
+|---|---|---|
+| `orchestration_plan` | `intent_id`、`template_hint`、`objective`、`risk_level`、`budget`、`metadata.tenant_id`、`metadata.project_id`、`metadata.correlation_id`、`agents[]` | 密钥、连接串、真实主机登录密码、NewAPI key 原文。 |
+| `agents[]` | `role_template`、`goal` | 让子 Agent 绕过 Manager/Agnet 审计的指令。 |
+| `runtime_execution` | 任一字段存在时 `profile_id` 必填 | 明文 kubeconfig、SSH key、云访问密钥。 |
+| `resource_grants[]` | `grant_id`、`resource_id`、`resource_type`、`tenant_id`、`project_id`、`target_role`、`target_agent_ref`、`permission_scope`、`status` | 明文 `password`、`token`、`private_key`、`access_key`、`credential`、数据库 DSN。 |
+| 日志/事件/审计返回 | `request_id` 或 `correlation_id`，以及发生时间 | 未脱敏命令行、环境变量 dump、密钥片段。 |
+| NewAPI 重建/部署场景 | `approval_id`、`rollback_command_ref`、健康检查引用、运行环境 `secret_ref` | 真实 VM 密码、PostgreSQL/Redis 连接串、NewAPI 服务令牌。 |
+
+### 8.2 联调验收清单
+
+- 创建部署请求只包含 `secret_ref`/`env://`/`runbook://` 引用，不包含真实凭据。
+- `tenant_id`、`project_id` 在 Header、metadata、resource grant 中一致。
+- `risk_level=high` 的生产运维任务包含 `approval_id` 和回滚引用。
+- 日志、事件、监控、审计接口都能通过 `correlation_id` 串联。
+- NewAPI 重建/部署只在实际执行并通过健康检查后标记为已部署；未执行时状态只能是 `planned`、`pending_approval`、`accepted` 或 `running`。
+- Manager 本地 `/api/agnet/*` 占位端点通过 payload 校验不等于生产 Agnet 平台已上线。
+
 ---

 ## 9. Manager 侧当前实现映射