Files

T

gongzhiyong 0dd1976519 docs: Agnet 可视化分工与 M5/愿景对齐；README 更新；同步 _all-in-one-upload

Made-with: Cursor

2026-04-30 11:06:58 +08:00

10 KiB

Raw Blame History

Agnet 平台 ↔ Heicode 集成接口设计（草案）

本文描述 Agnet 平台应向 Heicode（Manager / 客户端 / 自动化服务） 暴露的 控制面、数据面隔离、权限模型与可视化/事件接口。
路径、字段名为 设计意图；落地时可等价映射为 gRPC 或 GraphQL，但语义与隔离边界应保持一致。

关联里程碑：../milestones/ 中 M3～M5。

1. 设计目标

目标	说明
权界清晰	调用方身份可解析为「谁、属于哪一租户、具备何种角色」
租户默认隔离	无显式授权则不可读他租户资源
有状态可观测	执行单元生命周期与运行态可通过 API + 事件流呈现
可演进	资源带 `api_version` / schema 版本；破坏性变更走新版本路径

1.1 Agnet 可视化：Heicode Manager 与 Heicode 客户端的职责划分

使用方：团队与个人都会使用 Heicode；下列划分依据的是 信息类型与界面载体，不是「只有某类用户才用某一端」。

载体	主要职责	典型内容
Heicode Manager	呈现 Agnet 平台回传的运行态与性能类字段：编队/实例是否在跑、阶段（phase）、健康度、资源占用、队列与心跳、项目级聚合指标与近期错误摘要等。	控制台、Dashboard、与平台 SLA/运维相关的观测面。
Heicode（客户端）	在编码与工作会话过程中，实时或准实时展示子 Agnet（子执行单元）产出的内容（流式文本/结构化片段/工具结果等），与编辑、会话上下文同屏。	会话内输出面板、流式增量、与当前任务绑定的子代理交付物。

边界：Manager 侧重 平台契约下的状态与指标；Heicode 侧重 工作流中的执行输出。二者可调用同源底层 API，但不得把「平台大盘」与「子代理会话输出」混为同一套 UI 假设——后者通常带更强会话/项目上下文与更细粒度流式协议。

2. 身份与调用方式

2.1 服务间（推荐生产）

Heicode Manager 使用 服务账号 调用 Agnet：Authorization: Bearer <m2m_jwt>。
JWT 声明至少包含：sub（服务主体）、tenant_id（若适用）、scope（见 §3）、exp。
Agnet 校验Issuer（Manager 签发的委托令牌或 Agnet 签发的服务令牌，二选一应文档化）。

2.2 用户委派（可选）

终端用户经 Heicode OAuth 后，Manager 代发 用户委派令牌 访问 Agnet 只读/受限写接口；Claims 含 user_id、org_id、roles。

2.3 必需传递的上下文头（建议）

Header	必填	说明
`Authorization`	是	Bearer Token
`X-Request-Id`	强建议	全链路追踪
`X-Tenant-Id`	多租户时必填	顶层隔离键；与 Token 声明互相校验，不一致则 401
`X-Org-Id`	视模型	组织内子划分
`X-Project-Id`	编排相关 API 建议	资源挂载点
`X-Environment`	可选	`dev` / `staging` / `prod`
`X-Heicode-Correlation-Id`	强建议	与 Manager 审计日志关联

3. 权限模型（RBAC 概要）

3.1 角色（示例命名，可映射贵司 IAM）

角色	典型 scope	说明
`agnet:platform_admin`	全租户元数据、调试接口	极少人数
`agnet:org_admin`	本租户内项目、编队、凭据绑定
`agnet:project_editor`	指定项目下部署/停止/读状态
`agnet:operator_readonly`	读状态、读事件、读审计
`agnet:auditor`	仅审计与导出

3.2 权限分离原则

控制面（部署/改策略）与 观测面（读指标）可分角色授予。
凭据类写操作（绑定 Git Token、云 SA）单独 scope：agnet:credential:write。
拒绝隐式升级：只读 Token 不得通过查询参数绕过 body 校验升格为写操作。

4. 多租户与数据隔离

4.1 隔离键层级

Tenant（租户）
 └── Organization（可选）
      └── Project（项目）
           └── Deployment（一次编队部署）
                └── AgentInstance（执行单元实例）

所有持久化资源必须带 tenant_id；API 默认按 Token + Header 解析租户并 强制过滤。
跨租户引用：禁止在 URL 中使用「全局唯一但不带租户前缀」的裸 ID；推荐 tenant_scoped_id 或 (tenant_id, local_id) 复合。

4.2 数据面实现选项（择一或组合）

方案	适用	Agnet 侧责任
逻辑隔离	快速迭代	每张业务表 `tenant_id` + RLS 或统一拦截器
Schema 分库	强合规	每租户独立 schema / database
命名空间隔离（K8s）	执行单元运行时	编排器按租户分配 NS 与网络策略

4.3 负例测试（验收必备）

使用 Tenant A 的凭证访问 Tenant B 的 deployment_id → 403 或 404（对外不区分）。
列表接口默认不得返回其他租户资源，即使 ID 被猜到。

5. 编排与控制面 API（M3）

下列 REST 仅为示意；实际路径前缀可为 /api/v1 或 /agnet/v1。

5.1 部署编队

POST /deployments

请求体（示意）

{
  "project_id": "prj_xxx",
  "template": "agile_min",
  "correlation_id": "mgr_cor_abc",
  "parameters": {
    "unit_overrides": {}
  }
}

响应

{
  "deployment_id": "dep_yyy",
  "status": "accepted",
  "agent_instances": [
    { "instance_id": "agi_1", "role": "AG-PO", "phase": "pending" }
  ]
}

5.2 查询部署

GET /deployments/{deployment_id} —— 含租户校验。
POST /deployments/{deployment_id}:stop —— 优雅停止。

5.3 Webhook / 回调（Agnet → Heicode）

Manager 注册 URL：POST /integration/heicode/callback-config（或由 Agnet 控制台配置）。
负载含：deployment_id、instance_id、event_type、payload、occurred_at、signature。

签名：HMAC-SHA256（共享密钥或 JWKS）；拒绝无签名请求。

6. 运行态与可视化 API（M5）

与产品分工的对应关系：本章 §6.1～§6.3 主要支撑 Heicode Manager 上的平台运行态与聚合视图；§6.4 支撑 Heicode 客户端在编码过程中展示 子 Agnet 输出。总则见 §1.1。

6.1 实例快照

GET /agent-instances/{instance_id}

响应字段（示意）

{
  "instance_id": "agi_1",
  "deployment_id": "dep_yyy",
  "tenant_id": "ten_1",
  "role": "AG-PO",
  "phase": "running",
  "health": "ok",
  "last_heartbeat_at": "2026-04-30T12:00:00Z",
  "queue_depth": 2,
  "current_task": { "id": "task_7", "summary": "Review API draft" },
  "resource": { "cpu_pct": 12, "mem_mb": 512 },
  "errors_recent": [{ "at": "...", "code": "UPSTREAM_TIMEOUT", "message": "..." }]
}

6.2 项目级聚合

GET /projects/{project_id}/dashboard-snapshot

返回：活跃实例数、按 phase 分布、近 1h 失败率、平均任务耗时等 JSON 聚合（供 Heicode 控制台图表）。

6.3 指标导出（可选）

GET /metrics —— Prometheus 文本；或
GET /projects/{project_id}/metrics.json —— 简化 JSON。

6.4 子 Agnet 输出流（Heicode 编码侧）

面向 Heicode 客户端在会话内展示 子执行单元的产出（与 §6.1 的「实例心跳/资源占用」互补：此处强调 内容增量，而非仅状态字段）。

设计意图（路径可等价映射）：

GET /sessions/{session_id}/sub-agents/{sub_agent_id}/stream —— SSE，或
WS /sessions/{session_id}/stream —— 多路复用主题：sub_agent.output、sub_agent.tool_result 等。

data 示例（输出增量）

{
  "schema_version": 1,
  "type": "output_delta",
  "sub_agent_id": "sub_agi_1",
  "parent_turn_id": "turn_42",
  "content": { "mime": "text/markdown", "delta": "..." },
  "finished": false
}

鉴权与租户隔离与 §2～§4 一致；仅授权用户可读本会话下的子代理流。
若实际实现将子代理输出 嵌套在既有对话/Messages 协议中，须在联合 RFC 中声明字段映射，语义与本节一致即可。

7. 事件流（SSE / WebSocket）

两类订阅（勿混淆）：

平台/实例生命周期与运行态（与 §6.1、§6.2 对照）：阶段变更、健康、任务摘要等 —— 主要支撑 Heicode Manager 与状态面板。
会话内子代理输出与工具结果（与 §6.4 对照）—— 主要支撑 Heicode 客户端编码界面；实现上可与下述端点合并为多路事件，但 事件 type 必须可区分。

7.1 SSE（推荐易调试）

GET /agent-instances/{instance_id}/events

Headers：Accept: text/event-stream
事件：id、event、data（JSON）

data 示例

{
  "schema_version": 1,
  "type": "phase_changed",
  "from": "pending",
  "to": "running",
  "at": "2026-04-30T12:00:01Z"
}

7.2 WebSocket（高吞吐）

WS /projects/{project_id}/stream

首帧鉴权（query token 或子协议）；订阅主题：deployment.*、instance.*。

7.3 重连与顺序

支持 Last-Event-ID；服务端保留短期 环形缓冲（如 15 分钟）以便断线续传。

8. 审计与合规（跨 M4/M5）

GET /audit-logs?tenant_id=&from=&to= —— 仅 auditor / org_admin。
每条：actor、action、resource、tenant_id、request_id、correlation_id、result。

9. 错误模型

HTTP	含义	客户端行为
400	参数错误	展示校验细节
401	未认证	刷新令牌
403	权限不足	引导申请角色
404	不存在或无权（对外统一）	不泄漏存在性
409	状态冲突（重复部署）	幂等重试策略
429	限流	退避
503	编排背压	重试 + 降级文案

响应体统一 envelope：

{ "error": { "code": "FORBIDDEN_CROSS_TENANT", "message": "...", "request_id": "..." } }

10. 版本与演进

URL 前缀：/api/v1；破坏性变更引入 /api/v2。
事件 schema_version 递增；客户端忽略未知字段。

11. OpenAPI / 交付物建议

Agnet 侧维护 OpenAPI 3.1 与 异步 API（SSE/WS）说明；
提供 Postman Collection + 租户穿越测试集合。

本文档随里程碑评审更新；实现细节以 Agnet 与 Heicode 联合 RFC 为准。

10 KiB Raw Blame History Unescape Escape