From 6a3e91878770e0c9b9b5c8a1162d6ca05ac33334 Mon Sep 17 00:00:00 2001 From: gongzhiyong Date: Sun, 3 May 2026 18:05:45 +0800 Subject: [PATCH] docs: complete Agnet platform contract --- .../agnet-platform-request-contract.md | 256 +++++++++++++++++- 1 file changed, 251 insertions(+), 5 deletions(-) diff --git a/docs/integration/agnet-platform-request-contract.md b/docs/integration/agnet-platform-request-contract.md index 66a09b8..155a830 100644 --- a/docs/integration/agnet-platform-request-contract.md +++ b/docs/integration/agnet-platform-request-contract.md @@ -1,12 +1,35 @@ # Manager → Agnet 平台接口参数文档 -**版本**: v0.1（P1 最小可验证契约） -**方向**: Heicode Manager 主动请求 Agnet 平台；Agnet 平台返回部署、日志、监控与审计状态。 -**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志。 -**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`；不得传明文密码、Token、私钥、连接串或云访问密钥。 +**版本**: v0.2（P1/P5 联调契约） +**生效日期**: 2026-05-03 +**状态**: 联调准备；当前仓库提供 Manager 侧最小验证端点，生产 Agnet 平台部署尚未在本文档中宣称完成。 +**方向**: Heicode Manager 主动请求 Agnet 平台；Agnet 平台返回部署、日志、监控与审计状态。 +**范围**: 创建/停止子 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 | 否 | 审计上下文；不得含密钥字段。 | -### 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 侧当前实现映射