zhanggangyong/agent_management
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f306f2700b56af42e99147b0b6e5347323acce89
agent_management/docs/HEICODE_SUB_MODE_RUNTIME_INTEGRATION.md
T

14 KiB
Raw Blame History

Heicode Sub Mode Runtime 接入说明

更新时间：2026-06-01

本文档描述当前仓库作为 Sub Agile / 普通 sub 模式 Runtime 时，对 Manager 暴露的接入契约。

这不是客户端主调用协议。
生产客户端主调用协议应由 heicode-manager 的 /api/heicode/* 定义并统一归口。

1. 文档边界

当前仓库只负责：

  • sub_agile / 普通 sub 模式 Runtime
  • Manager 下发后已校验的执行计划
  • Runtime 事实回传：状态、事件、产物、审批请求、诊断信息

当前仓库不负责：

  • 真正的 Swarm 产品模式
  • 客户端主调用协议
  • 客户端展示状态裁决
  • 本地修改的最终可信版本管理
  • 云部署目标选择与云密钥直连

命名约定：

  • agent：主命名，新的标准入口
  • agnet：兼容命名，历史调用方继续可用
  • /api/swarms：sub-mode compatibility API，不表示当前仓库实现独立 Swarm 系统

生产调用边界：

客户端 -> Manager /api/heicode/sub-agile/*
Manager -> agent_management /api/agent/sub-agile/*
agent_management -> Manager /api/agent/callbacks/runtime-events
客户端 <- Manager display_status / workflow / artifacts / diagnostics

结论：

  • 生产客户端不应直连本 Runtime
  • 本文档面向 Runtime 接入方、Manager 调用方、联调工程师

2. 主路径与兼容路径

2.1 主路径

GET  /api/agent/health

POST /api/agent/sub-agile/deployments
GET  /api/agent/sub-agile/deployments
GET  /api/agent/sub-agile/deployments/{deployment_id}
POST /api/agent/sub-agile/deployments/{deployment_id}/stop
POST /api/agent/sub-agile/deployments/{deployment_id}/approvals/{approval_id}
GET  /api/agent/sub-agile/deployments/{deployment_id}/logs
GET  /api/agent/sub-agile/deployments/{deployment_id}/events
GET  /api/agent/sub-agile/deployments/{deployment_id}/metrics

POST /api/agent/callbacks/runtime-events
GET  /api/agent/callbacks/runtime-events/schema

2.2 兼容路径

GET  /api/agnet/health
POST /api/agnet/deployments
GET  /api/agnet/deployments
GET  /api/agnet/deployments/{deployment_id}
POST /api/agnet/deployments/{deployment_id}/stop
POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
GET  /api/agnet/deployments/{deployment_id}/logs
GET  /api/agnet/deployments/{deployment_id}/events
GET  /api/agnet/deployments/{deployment_id}/metrics
POST /api/agnet/callbacks/swarm-events
GET  /api/agnet/callbacks/swarm-events/schema

2.3 Legacy compatibility API

POST /api/swarms
GET  /api/swarms/{swarm_id}
GET  /api/swarms/{swarm_id}/status
POST /api/swarms/{swarm_id}/stop
GET  /api/swarms/{swarm_id}/logs
GET  /api/swarms/{swarm_id}/events
GET  /api/swarms/{swarm_id}/metrics
GET  /api/swarms/{swarm_id}/artifacts/{artifact_id}/content
POST /api/swarms/{swarm_id}/approvals/{approval_id}

2.4 用户态产物 / 时间线查询

当前仓库仍保留以下内部 / 兼容查询面：

GET /api/agent/user/deployments/{deployment_id}/artifacts
GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
GET /api/agent/user/deployments/{deployment_id}/timeline
GET /api/agent/user/deployments/{deployment_id}/sk-snapshots

说明：

  • 这些路径更适合作为 Runtime / Manager 内部或兼容查询面
  • 生产客户端不应直接消费这些路径
  • 生产客户端应通过 Manager 的 /api/heicode/* 查询 artifacts / workflow / diagnostics

3. 状态语义与裁决边界

3.1 Runtime 当前返回状态集合

当前 Runtime 对外统一投影：

accepted
running
waiting_approval
completed
failed
stopped

3.2 Runtime 状态不等于客户端展示状态

统一方案中应区分：

client_task_status
cloud_deployment_status
runtime_execution_status
display_status

当前 Runtime 返回的 status 更接近：

runtime_execution_status

尤其需要注意：

  • Runtime completed 不等于用户最终看到的 completed
  • 最终 display_status 必须由 Manager 根据结构化产物事实裁决

Manager 可能额外裁决出：

queued
runtime_syncing
runtime_accepted
waiting_input
completed_without_deliverable
needs_codegen
offline_pending

推荐裁决原则：

Runtime completed + has_deliverable=true + summary_only=false -> completed
Runtime completed + summary_only=true -> completed_without_deliverable 或 needs_codegen
Runtime completed + 无真实 artifact -> completed_without_deliverable 或 needs_codegen

4. 推荐请求结构

建议 Manager 传入结构化 sub mode 计划，而不是裸自然语言。

示例：

{
  "orchestration_plan": {
    "intent_id": "task_demo_001",
    "template_hint": "fastapi-crud",
    "objective": "为任务管理系统生成 FastAPI CRUD 后端方案",
    "sub_mode": "agile",
    "user_context": {
      "user_id": "user_123",
      "binding_scope": "project_task_demo_001"
    },
    "agile_context": {
      "stage": "planning",
      "checkpoint": "draft_created",
      "max_iterations": 1
    },
    "budget": {
      "max_cost_usd": 1,
      "max_tokens": 2000,
      "max_duration_sec": 600,
      "alert_threshold_pct": 80
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "gpt-5.4",
      "allowed_model_ids": ["gpt-5.4"],
      "stream": false
    },
    "agents": [
      {
        "role": "backend",
        "template": "a2a_litellm_agent",
        "model": "gpt-5.4",
        "capabilities": ["code", "api", "test"]
      }
    ]
  },
  "callback": {
    "url": "https://your-manager.example.com/api/agent/callbacks/runtime-events"
  }
}

最低必填项：

  • orchestration_plan
  • orchestration_plan.sub_mode
  • orchestration_plan.user_context.user_id
  • callback.url

5. 模型来源与信任边界

生产环境中，Runtime 不应信任客户端直传的模型选择。

正确边界：

客户端选择模型
Manager 校验模型、套餐、权限、预算、allowed_model_ids
Manager 下发已校验 orchestration_plan
Runtime 只消费 Manager 下发的 model / billing_context / allowed_model_ids

约定：

  • Runtime 只信任 Manager 已校验的 orchestration_plan
  • Runtime 不应把客户端未校验的 model 视为最终可信配置

6. 回调事件

主回调入口：

POST /api/agent/callbacks/runtime-events

兼容回调入口：

POST /api/agnet/callbacks/swarm-events

当前支持的关键事件：

  • deployment.status_changed
  • phase.changed
  • timeline.updated
  • agent.started
  • agent.completed
  • agent.crashed
  • approval.requested
  • artifact.created
  • task.completed
  • task.failed
  • task.blocked
  • sk_tool.called
  • sk_tool.completed
  • sk_tool.failed
  • budget.alert

最小消费建议：

  1. deployment.status_changed
  2. phase.changed
  3. artifact.created
  4. approval.requested

7. 产物语义

7.1 当前真实 artifact

当前 Runtime 真实产物通常以：

  • code_patch
  • document

返回，并提供：

  • artifact_id
  • summary
  • uri
  • metadata.download_path

7.2 fallback artifact

当真实 agent 没有产出具体 artifact 时，Runtime 会生成 fallback artifact。

从本次升级开始，fallback artifact 必须稳定标记：

{
  "metadata": {
    "synthesized": true,
    "summary_only": true
  }
}

语义说明：

  • synthesized=true：说明该产物是 Runtime 合成的兼容性结果
  • summary_only=true：说明该产物只适合展示失败 / 总结，不应直接作为代码类任务的有效交付依据

Manager 不应将 summary_only=true 的 artifact 作为代码任务 completed 的充分条件。

7.3 project_folder artifact（结构性代码强制要求）

对于结构性代码交付，统一方案要求优先使用：

artifact_type = project_folder

适用范围：

  • 前后端项目
  • 多文件项目
  • 可部署项目
  • 包含 frontend/backend/docs/deploy 等目录的结构性代码任务

约束：

  • code_patch / document 仅适用于单文件、小型补丁或兼容任务
  • 对于结构性代码任务，Runtime 不应长期只返回单一 content 正文作为主要交付形式

推荐形态：

{
  "artifact_id": "art_project_xxx",
  "artifact_type": "project_folder",
  "title": "Oracle Cloud Agency Site",
  "summary": "包含 frontend、backend、docs 和部署配置的完整项目。",
  "metadata": {
    "root_dir": "oracle-cloud-agency-site",
    "manifest_uri": "runtime://run_xxx/artifacts/art_project_xxx/manifest",
    "archive_uri": "runtime://run_xxx/artifacts/art_project_xxx/archive.zip",
    "content_hash": "sha256:project-tree-hash",
    "file_count": 42,
    "directory_count": 8
  }
}

当前仓库现状说明：

  • 当前实现仍以 single_file_content 作为主要真实产物形态
  • 结构性代码任务尚未默认落成 project_folder
  • 这属于当前实现缺口，不应被视为最终统一协议目标

接入方应按以下原则理解：

  • 当前 content 路径仍可用于兼容读取单文件/摘要类产物
  • 未来结构性代码交付应升级为 project_folder + manifest/archive/files

7.4 project_folder 读取路径

对于 project_folder 类型 artifact，主读取路径应是：

manifest_uri
archive_uri
files/{path}

推荐读取顺序：

  1. 先读 manifest_uri 获取项目文件树和 revision 信息
  2. 按需通过 files/{path} 读取单文件
  3. 需要整体下载时通过 archive_uri

content 接口定位：

  • content 仅作为 code_patch / document / single_file_content 的兼容读取方式
  • project_folder 不应依赖单一 content 接口作为主读取方式

8. 本地修改与 artifact revision（推荐扩展）

统一方案要求：

  • 用户本地修改项目文件夹，不等于云端产物自动更新
  • 客户端必须显式上传 local edit
  • Manager 保存 project artifact revision
  • Runtime 后续执行必须以最新 accepted revision 为基线

当前仓库尚未把这套 revision 协议实现为正式 Runtime 接口，但建议保留以下扩展方向：

POST /api/agent/sub-agile/deployments/{deployment_id}/artifact-edits

推荐事件形态：

{
  "event_type": "artifact.local_edit_received",
  "task_id": "task_xxx",
  "deployment_id": "dep_xxx",
  "runtime_deployment_id": "run_xxx",
  "artifact_id": "art_project_xxx",
  "project_revision": 2,
  "source": "client_local_edit",
  "manifest_uri": "manager://tasks/task_xxx/artifacts/art_project_xxx/revisions/2/manifest",
  "archive_uri": "manager://tasks/task_xxx/artifacts/art_project_xxx/revisions/2/archive",
  "content_hash": "sha256:new"
}

后续建议补齐的 revision 细节：

  • base_project_revision
  • base_content_hash
  • ARTIFACT_REVISION_CONFLICT
  • artifact.local_edit_applied
  • artifact.local_edit_reviewed
  • artifact.local_edit_rejected

推荐边界：

  • Manager 负责 revision / conflict 判定
  • Runtime 通过 manifest/archive/files 读取指定 accepted revision

9. 云部署生命周期（推荐扩展）

统一方案中，云部署不应由客户端直传云密钥并直接驱动 Runtime。

正确边界：

客户端只选择 target / environment / resource_binding_id
Manager 负责校验、审批、凭证解析、预算和审计
Runtime 或 Deploy Worker 执行 provider adapter
部署结果通过 deployment_manifest artifact 和 deployment events 回传

当前 Runtime 文档仅做说明，不将云部署声明为本仓库已完整实现能力。

10. 真实联调建议

10.1 当前稳定范围

当前 Runtime 更稳定的任务类型：

  • 小型单文件函数生成
  • 小型 React 组件生成
  • 中小型实现摘要 / 代码骨架任务
  • 经输出收缩后的中型真实编程任务

10.2 当前高风险任务

高风险特征：

  • 一次性要求完整项目所有文件
  • 单 agent 输出过长代码、长解释、长测试、长部署说明
  • 多角色同时高负载、每个角色都要求大体量正文

真实现象：

  • 较大的任务可能在模型网关返回 504 Gateway Time-out

10.3 推荐拆分方式

建议把一个大任务拆成多个小任务：

  • 先生成数据模型与 API 列表
  • 再生成 CRUD 路由骨架
  • 再生成测试样例
  • 前端组件与样式单独生成
  • reviewer 单独作为收尾检查任务

11. 模型网关配置要求

当前 runtime agent 需要一个真正返回模型 JSON 的 OpenAI 兼容基址。

当前线上有效配置是：

https://code.xinghanlab.com/v1

不是：

https://code.xinghanlab.com

如果少了 /v1，subagent 实际打到的会是站点 HTML，而不是模型接口，结果会出现：

  • JSON 解析失败
  • artifact 为空
  • 或整体任务失败

建议至少确保以下配置正确：

  • HEICODE_NEWAPI_BASE_URL=https://code.xinghanlab.com/v1
  • LITELLM_BASE_URL=https://code.xinghanlab.com/v1

12. 最小验证流程

12.1 服务与契约验证

curl http://127.0.0.1:8000/api/agent/health
curl http://127.0.0.1:8000/api/agnet/health
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/test_sub_mode_runtime_contract.py -q

12.2 真实 smoke 验证

建议至少跑一条小型真实编程任务，例如：

  • 生成 Python 工具函数 + pytest
  • 生成 React 小组件 + CSS

成功标准：

  1. 创建响应返回 accepted
  2. Runtime 最终状态到 completed
  3. artifacts 非空
  4. artifacts/{artifact_id}/content 返回可读正文，而不是 UUID、HTML 或空串
  5. fallback artifact 必须带 synthesized=true / summary_only=true

13. 相关文件

主入口与兼容入口：

状态投影：

K8s 部署与配置：

如果接入方只想记最关键的四件事，只需要记：

  1. 生产客户端只调用 Manager 的 /api/heicode/*
  2. Manager 调 Runtime 统一走 /api/agent/sub-agile/*
  3. Runtime completed 只是 runtime_execution_status，不等于最终 display_status
  4. summary_only=true 的 artifact 不能直接当代码类任务有效交付物
Reference in New Issue View Git Blame Copy Permalink