Files

T

elipitc 1b49887819 Sync sub-mode runtime docs and k8s updates

2026-06-01 23:10:33 +08:00

16 KiB

Raw Blame History

Heicode 对接需求实现情况报告

生成日期: 2026-05-12
最近同步: 2026-05-29
对比文档: plans/Agent-Manager-Heicode对接需求文档(2).md
当前分支: feature/code-ai-agent-test
部署版本: heicode-v2-20260529120632

2026-05-29 补充：本文最初记录 Phase 1-5 实现状态。最新普通 sub 敏捷模式联调更新请优先阅读 docs/HEICODE_V2_1_4_UPDATE_SUMMARY.md 和 docs/HEICODE_API_INTEGRATION.md。下方保留原阶段性报告结构，并同步标注 v2.1.6 已补齐的能力。

📊 总体实现进度

类别	需求数量	已实现	部分实现	未实现	完成度
核心 API 接口	12	11	0	1	92%
认证和安全	5	5	0	0	100%
数据模型	8	8	0	0	100%
K8s 集成	6	4	2	0	67%
Vault 集成	4	2	2	0	50%
模型网关路由	3	3	0	0	100%
总计	38	33	4	1	87%

v2.1.6 新增完成项

能力	状态	说明
`/api/swarms` Runtime 兼容入口	✅ 完成	支持创建、详情、状态、停止、日志、事件、指标和审批 decision
Runtime 主动 callback	✅ 完成	支持 status、phase、timeline、agent、tool、artifact、approval、budget 事件
普通 sub artifact 回调	✅ 完成	普通 sub agent 真实执行完成后会生成 `artifact.created`，用户态 artifacts 不再固定为 0
普通 sub task 终态	✅ 完成	新增 `task.completed` / `task.failed` / `task.blocked` 回调
deployment/agent 状态一致性	✅ 完成	deployment 完成或失败时，agents 会同步进入终态
`/api/swarms/{id}/logs` 兜底日志	✅ 完成	返回 Runtime 聚合日志摘要，而不是固定占位文本
Callback HMAC/幂等接收	✅ 完成	支持 v2.1 HMAC，兼容旧 service token
artifact 查询	✅ 完成	`GET /api/agent/user/deployments/{deployment_id}/artifacts`
timeline 查询	✅ 完成	`GET /api/agent/user/deployments/{deployment_id}/timeline`
SK snapshot 查询投影	✅ 完成	`GET /api/agent/user/deployments/{deployment_id}/sk-snapshots`
审批 decision	✅ 完成	支持 `/api/swarms/.../approvals/...` 与 `/api/agent/sub-agile/deployments/.../approvals/...`

✅ 已完成功能（33项）

1. 核心 API 接口（11/12）

✅ 已实现的接口

接口	路径	状态	文件位置
1️⃣ 健康检查	`GET /api/agent/health`	✅ 完成	`api/agnet/router.py:20`
2️⃣ 创建部署	`POST /api/agent/sub-agile/deployments`	✅ 完成	`api/agnet/deployments.py:123`
3️⃣ 列出部署	`GET /api/agent/sub-agile/deployments`	✅ 完成	`api/agnet/deployments.py:346`
4️⃣ 获取部署详情	`GET /api/agent/sub-agile/deployments/{id}`	✅ 完成	`api/agnet/deployments.py:408`
5️⃣ 停止部署	`POST /api/agent/sub-agile/deployments/{id}/stop`	✅ 完成	`api/agnet/deployments.py:469`
6️⃣ 获取日志	`GET /api/agent/sub-agile/deployments/{id}/logs`	✅ 完成	`api/agnet/deployments.py:596`
7️⃣ 获取事件	`GET /api/agent/sub-agile/deployments/{id}/events`	✅ 完成	`api/agnet/deployments.py:679`
8️⃣ 获取指标	`GET /api/agent/sub-agile/deployments/{id}/metrics`	✅ 完成	`api/agnet/deployments.py:731`
9️⃣ Runtime 兼容入口	`POST /api/swarms`	✅ 完成	`api/swarm/router.py`
🔟 Callback 接收	`POST /api/agent/callbacks/runtime-events`	✅ 完成	`api/agnet/callbacks.py`
1️⃣1️⃣ 用户态观测	`/api/agent/user/deployments/{id}/{artifacts,timeline,sk-snapshots}`	✅ 完成	`api/agnet/callbacks.py`

实现亮点:

✅ 完整的请求/响应模型定义
✅ 幂等性支持（Idempotency-Key）
✅ 分页支持（cursor-based）
✅ 日志脱敏机制
✅ 审计日志记录
✅ 错误码标准化

2. 认证和安全（5/5）

功能	状态	实现位置
Service Token 认证	✅ 完成	`api/agnet/auth.py:verify_service_token`
Header 提取和验证	✅ 完成	`api/agnet/auth.py:extract_headers`
敏感字段检测	✅ 完成	`api/agnet/validators.py:validate_no_sensitive_fields`
Vault 引用验证	✅ 完成	`api/agnet/validators.py:validate_vault_references`
审计日志记录	✅ 完成	`api/agnet/deployments.py:create_audit_log`

实现细节:

# 认证中间件
@router.post("/deployments")
async def create_deployment(
    token: str = Depends(verify_service_token)  # ✅ Token 验证
):
    headers = extract_headers(request)  # ✅ Header 提取
    validate_no_sensitive_fields(payload)  # ✅ 敏感字段检测
    validate_vault_references(payload)  # ✅ Vault 引用验证

3. 数据模型（8/8）

模型	状态	文件位置
CreateDeploymentRequest	✅ 完成	`api/agnet/models.py`
DeploymentStatus 枚举	✅ 完成	`database.py`
RiskLevel 枚举	✅ 完成	`database.py`
BillingProvider 枚举	✅ 完成	`database.py`
AgentInstance 模型	✅ 完成	`database.py`
Event 模型	✅ 完成	`database.py`
AuditLog 模型	✅ 完成	`database.py`
响应模型（8个）	✅ 完成	`api/agnet/models.py`

4. K8s 集成（4/6）

功能	状态	实现位置
Namespace 创建	✅ 完成	`api/agnet/k8s_manager.py:create_namespace`
Pod 创建	✅ 完成	`api/agnet/k8s_manager.py:create_pod`
ConfigMap 创建	✅ 完成	`api/agnet/k8s_manager.py:create_configmap`
Pod 日志获取	✅ 完成	`api/agnet/k8s_manager.py:get_pod_logs`
Pod 状态查询	⚠️ 部分	`api/agnet/k8s_manager.py:get_pod_status`
ServiceAccount 管理	⚠️ 部分	需要增强

5. Vault 集成（2/4）

功能	状态	实现位置
Vault 客户端初始化	✅ 完成	`api/agnet/vault_client.py`
密钥获取接口	✅ 完成	`api/agnet/vault_client.py:get_secret`
Kubernetes Auth	⚠️ 部分	需要配置
Workload Identity	⚠️ 部分	需要 AKS 配置

6. 模型网关路由（3/3）

功能	状态	实现说明
Provider 字段验证	✅ 完成	支持 `newapi` 和 `litellm`
NewAPI Token 注入	✅ 完成	环境变量 `HEICODE_NEWAPI_USER_TOKEN`
LiteLLM Token 注入	✅ 完成	环境变量 `LITELLM_USER_KEY`

实现代码:

# 按 provider 路由模型网关
configmap_data = {
    "MODEL_GATEWAY_URL": (
        settings.HEICODE_NEWAPI_BASE_URL 
        if request.billing_context.provider.value == "newapi" 
        else settings.LITELLM_BASE_URL
    ),
}

⚠️ 部分实现功能（4项）

1. ServiceAccount 自动创建和绑定

当前状态: 基础实现，需要增强

已实现:

✅ 基础 ServiceAccount 创建

待完善:

⚠️ 按 role-{user_id} 命名规则
⚠️ Vault Kubernetes Auth Role 绑定
⚠️ Workload Identity 注解

需要补充:

def create_service_account(self, namespace: str, role: str, user_id: str):
    sa_name = f"sa-{role}-{hashlib.sha256(user_id.encode()).hexdigest()[:6]}"
    sa = client.V1ServiceAccount(
        metadata=client.V1ObjectMeta(
            name=sa_name,
            annotations={
                "azure.workload.identity/client-id": "<managed-identity-id>",
                "vault.hashicorp.com/role": f"heicode-{user_id}"
            }
        )
    )
    self.v1.create_namespaced_service_account(namespace, sa)

2. ConfigMap 三文件格式

当前状态: 基础实现，需要完善格式

已实现:

✅ ConfigMap 创建
✅ 基础配置注入

待完善:

⚠️ AGENT.md 格式化
⚠️ resource_context.json 结构
⚠️ permission_manifest.json 结构

3. Vault Kubernetes Auth

当前状态: 客户端已实现，需要配置

已实现:

✅ Vault 客户端封装
✅ 密钥获取接口

待配置:

⚠️ Vault 服务器地址
⚠️ Kubernetes Auth 路径
⚠️ Policy 配置

4. Pod 日志脱敏

当前状态: 基础实现，需要增强

已实现:

✅ 日志获取
✅ 基础脱敏标记

待增强:

⚠️ 正则匹配敏感信息
⚠️ 自动掩码处理
⚠️ 脱敏规则配置

❌ 未实现 / 后续增强功能（1项 + 2项增强）

1. SSE 实时日志流

接口: GET /api/agent/sub-agile/deployments/{id}/logs/stream

状态: ❌ 未实现

优先级: 低（标记为可选）

实现建议:

from fastapi.responses import StreamingResponse

@router.get("/deployments/{deployment_id}/logs/stream")
async def stream_logs(deployment_id: str):
    async def log_generator():
        while True:
            logs = await get_new_logs(deployment_id)
            for log in logs:
                yield f"data: {json.dumps(log)}\n\n"
            await asyncio.sleep(1)
    
    return StreamingResponse(
        log_generator(),
        media_type="text/event-stream"
    )

2. 资源作用域监控快照

接口: GET /api/agent/projects/{binding_scope}/dashboard-snapshot

状态: ⚠️ 后续增强

优先级: 中

需要返回:

active_instances
phase_distribution
failure_rate_1h
avg_task_duration
budget (tokens/cost/duration)
resource_usage (cpu/mem/network)

3. SK 快照解析

接口: POST /api/agent/sk-snapshots/resolve

状态: ⚠️ 后续增强

优先级: 中

功能说明: 拉取 git/upload 资源，生成只读快照。v2.1.4 已支持从 Runtime callback payload 投影查询 SK snapshot，独立解析接口仍待补齐。

4. SK 快照查询

接口: GET /api/agent/user/deployments/{id}/sk-snapshots

状态: ✅ 已实现（v2.1.4）

优先级: 已完成

功能说明: 从 sk_tool.called、sk_tool.completed、sk_tool.failed 和携带 sk_snapshot 的 artifact callback payload 投影返回快照列表。独立快照解析与物化存储可在后续增强。

📁 代码结构

api/agnet/
├── __init__.py              # 模块初始化
├── router.py                # 主路由（38 行）
├── auth.py                  # 认证中间件（1,512 字节）
├── models.py                # 数据模型（7,691 字节）
├── deployments.py           # 部署管理接口（27,888 字节）⭐ 核心
├── validators.py            # 请求验证（4,097 字节）
├── idempotency.py           # 幂等性缓存（2,096 字节）
├── k8s_manager.py           # K8s 操作封装（7,608 字节）
└── vault_client.py          # Vault 客户端（5,361 字节）

总计: ~1,756 行代码

🔍 关键实现细节

1. 创建部署流程

# api/agnet/deployments.py:123
@router.post("/deployments")
async def create_deployment(...):
    # 1. 幂等性检查
    if idempotency_key:
        cached = idempotency_cache.get(idempotency_key)
        if cached:
            return cached
    
    # 2. 请求验证
    validate_deployment_request(request, headers)
    
    # 3. 创建数据库记录
    deployment = Deployment(...)
    db.add(deployment)
    
    # 4. 创建 K8s 资源
    k8s_manager.create_namespace(namespace)
    k8s_manager.create_configmap(namespace, configmap_name, data)
    k8s_manager.create_pod(namespace, pod_name, image, env_vars)
    
    # 5. 创建审计日志
    create_audit_log(db, actor, action, resource_id, result)
    
    # 6. 返回响应
    return CreateDeploymentResponse(...)

2. 模型网关路由

# 根据 billing_context.provider 决定模型网关
if request.billing_context.provider.value == "newapi":
    # Heicode NewAPI
    model_gateway_url = settings.HEICODE_NEWAPI_BASE_URL
    token_env_name = "HEICODE_NEWAPI_USER_TOKEN"
else:
    # taijiagent LiteLLM
    model_gateway_url = settings.LITELLM_BASE_URL
    token_env_name = "LITELLM_USER_KEY"

# 从 Vault 获取 token
model_gateway_secret = await vault_client.get_secret(
    request.billing_context.secret_ref
)

# 注入 Pod 环境变量
env_vars[token_env_name] = model_gateway_secret

3. 日志脱敏

# api/agnet/deployments.py:596
@router.get("/deployments/{deployment_id}/logs")
async def get_deployment_logs(...):
    # 获取 Pod 日志
    pod_logs = k8s_manager.get_pod_logs(namespace, pod_name)
    
    # 解析并脱敏
    for line in pod_logs.split('\n'):
        logs.append(LogEntry(
            message=line,  # TODO: 需要增强脱敏逻辑
            redacted=True if contains_sensitive(line) else False
        ))
    
    return GetLogsResponse(logs=logs)

🎯 下一步工作建议

Phase 1: 完善核心功能（1-2 天）

优先级: 高

✅ 增强 ServiceAccount 创建逻辑
- 实现 sa-{role}-{user_hash} 命名
- 添加 Vault 和 Workload Identity 注解
✅ 完善 ConfigMap 三文件格式
- AGENT.md 模板化
- resource_context.json 结构化
- permission_manifest.json 标准化
✅ 增强日志脱敏
- 正则匹配敏感信息
- 自动掩码处理

Phase 2: 实现缺失接口（2-3 天）

优先级: 中

⚪ 实现资源作用域监控快照
- GET /api/agent/projects/{binding_scope}/dashboard-snapshot
⚪ 实现 SK 快照功能
- POST /api/agent/sk-snapshots/resolve
- GET /api/agent/sub-agile/deployments/{id}/sk-snapshots

Phase 3: 基础设施配置（3-5 天）

优先级: 中

⚪ 配置 Vault Kubernetes Auth
- 部署 Vault 服务器
- 配置 Auth 路径和 Policy
⚪ 配置 AKS Workload Identity
- 启用 OIDC Issuer
- 配置 Federated Identity

Phase 4: 可选功能（1-2 天）

优先级: 低

⚪ 实现 SSE 实时日志流
- GET /api/agent/sub-agile/deployments/{id}/logs/stream

📊 与需求文档对比

需求章节	完成度	说明
§2 - 12 个新接口	92%	11/12 已实现，SSE 日志流待补齐
§3 - 接口详情	80%	核心逻辑完成，细节待完善
§3a - 模型网关路由	100%	✅ 完全实现
§4 - Pod 启动改造	70%	基础完成，SA 和 ConfigMap 待增强
§5 - AKS 基础设施	40%	需要基础设施团队配合
§6 - 向后兼容	100%	✅ 老接口完全不受影响

✅ 结论

当前状态

总体完成度: 87%

✅ 核心功能已实现: 11/12 API 接口完成
✅ 认证和安全完善: 100% 完成
✅ 模型网关路由: 100% 完成
⚠️ 部分功能待完善: ServiceAccount、ConfigMap、日志脱敏
❌ 1 个接口待实现: SSE 日志流
⚠️ 2 个后续增强项: 资源作用域监控快照、SK 快照解析/物化存储

AKS 部署版本

当前 AKS 上的版本是 heicode-v2-20260529120632，包含：

✅ 完整的 Heicode Agent API (/api/agent/*)
✅ /api/swarms Runtime 兼容入口
✅ Runtime 主动 callback、artifact、timeline、SK snapshot 查询
✅ 普通 sub 真实执行后的 artifact.created 与 task.* 终态回调
✅ deployment 与 agents 终态一致性修复
✅ /api/swarms/{id}/logs Runtime 聚合日志摘要
✅ 审批 decision 接收路径
✅ 部署管理、日志、事件、指标功能
✅ 模型网关路由（NewAPI/LiteLLM）
✅ Vault 集成基础
✅ 审计日志和事件追踪

可以开始对接

是的，当前代码已经可以开始对接！

核心 API 和普通 sub 联调能力已经实现，可以支持：

✅ 创建和管理部署
✅ 查询部署状态和详情
✅ 获取日志和事件
✅ 监控资源指标
✅ 模型网关路由
✅ Runtime callback 回写 timeline / artifact / SK snapshot
✅ 高风险动作审批流

剩余的 SSE 日志流、监控快照和 SK 快照解析/物化存储可以在后续迭代中补充。

文档版本: v1.1
生成时间: 2026-05-12
最近同步: 2026-05-29
维护者: Agent Manager Team

16 KiB Raw Blame History Unescape Escape

Heicode 对接需求实现情况报告

📊 总体实现进度

v2.1.6 新增完成项

✅ 已完成功能（33项）

1. 核心 API 接口（11/12）

✅ 已实现的接口

2. 认证和安全（5/5）

3. 数据模型（8/8）

4. K8s 集成（4/6）

5. Vault 集成（2/4）

6. 模型网关路由（3/3）

⚠️ 部分实现功能（4项）

1. ServiceAccount 自动创建和绑定

2. ConfigMap 三文件格式

3. Vault Kubernetes Auth

4. Pod 日志脱敏

❌ 未实现 / 后续增强功能（1项 + 2项增强）

1. SSE 实时日志流

2. 资源作用域监控快照

3. SK 快照解析

4. SK 快照查询

📁 代码结构

🔍 关键实现细节

1. 创建部署流程

2. 模型网关路由

3. 日志脱敏

🎯 下一步工作建议

Phase 1: 完善核心功能（1-2 天）

Phase 2: 实现缺失接口（2-3 天）

Phase 3: 基础设施配置（3-5 天）

Phase 4: 可选功能（1-2 天）

📊 与需求文档对比

✅ 结论

当前状态

AKS 部署版本

可以开始对接

16 KiB

Raw Blame History