From ab71d5b72b27951e5bde298548e8eb6bb4671ab4 Mon Sep 17 00:00:00 2001 From: gongzhiyong Date: Sat, 2 May 2026 23:42:51 +0800 Subject: [PATCH] docs: add agnet platform request contract --- docs/README.md | 3 +- .../agnet-platform-request-contract.md | 634 ++++++++++++++++++ 2 files changed, 636 insertions(+), 1 deletion(-) create mode 100644 docs/integration/agnet-platform-request-contract.md diff --git a/docs/README.md b/docs/README.md index ba26f49..2d3b99b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,12 +1,13 @@ # Heicode Docs -当前 `docs/` 只保留三类主线文档： +当前 `docs/` 只保留四类主线文档： | 文档 | 用途 | |------|------| | [`heicode.md`](./heicode.md) | Heicode 当前产品定位、系统边界和架构共识 | | [`plan.md`](./plan.md) | 按当前共识拆出的实施计划 | | [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md) | 已上线登录接口对接文档 | +| [`integration/agnet-platform-request-contract.md`](./integration/agnet-platform-request-contract.md) | Manager 请求 Agnet 平台时携带的部署、日志、监控、事件与审计接口参数 | 旧 Agnet API 草案、旧里程碑、旧架构说明和旧上手材料不再作为实施依据。后续文档和实现以 `heicode.md` 与 `plan.md` 为准。 diff --git a/docs/integration/agnet-platform-request-contract.md b/docs/integration/agnet-platform-request-contract.md new file mode 100644 index 0000000..66a09b8 --- /dev/null +++ b/docs/integration/agnet-platform-request-contract.md @@ -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 服务身份令牌，由 Secret Store/运行环境注入。 | +| `Content-Type: application/json` | POST/PUT 是 | JSON 请求体。 | +| `X-Tenant-Id: ` | 是 | 租户边界；必须等于 body/query 中 tenant_id。 | +| `X-Project-Id: ` | 建议 | 项目边界，便于平台鉴权与审计。 | +| `X-Correlation-Id: ` | 是 | Manager 生成，全链路追踪。 | +| `X-Request-Id: ` | 建议 | 单次 HTTP 请求追踪 ID，可与 correlation_id 不同。 | +| `Idempotency-Key: ` | 创建类接口建议 | 避免重试造成重复部署。 | + +### 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 | 否 | 路径、分支、区域、超时等限制；不得含密钥字段。 | +| `metadata` | object | 否 | 资源展示/审计元数据；不得含密钥字段。 | +| `status` | enum | 是 | `pending` / `active` / `disabled` / `revoked`。 | +| `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 | +| `audit` | object | 否 | 审计上下文；不得含密钥字段。 | + +### 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 端点仅作为最小验证与控制面占位，不代表所有日志/监控平台能力已完整实现。