agent_management/docs/HEICODE_SUB_MODE_RUNTIME_INTEGRATION.md

# 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 系统

生产调用边界：

```text
客户端 -> 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 主路径

```text
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 兼容路径

```text
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

```text
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 用户态产物 / 时间线查询

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

```text
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 对外统一投影：

```text
accepted
running
waiting_approval
completed
failed
stopped
```

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

统一方案中应区分：

```text
client_task_status
cloud_deployment_status
runtime_execution_status
display_status
```

当前 Runtime 返回的 `status` 更接近：

```text
runtime_execution_status
```

尤其需要注意：

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

Manager 可能额外裁决出：

```text
queued
runtime_syncing
runtime_accepted
waiting_input
completed_without_deliverable
needs_codegen
offline_pending
```

推荐裁决原则：

```text
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 计划，而不是裸自然语言。

示例：

```json
{
  "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 不应信任客户端直传的模型选择。

正确边界：

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

约定：

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

## 6. 回调事件

主回调入口：

```text
POST /api/agent/callbacks/runtime-events
```

兼容回调入口：

```text
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 必须稳定标记：

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

语义说明：

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

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

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

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

```text
artifact_type = project_folder
```

适用范围：

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

约束：

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

推荐形态：

```json
{
  "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，主读取路径应是：

```text
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 接口，但建议保留以下扩展方向：

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

推荐事件形态：

```json
{
  "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。

正确边界：

```text
客户端只选择 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 兼容基址。

当前线上有效配置是：

```text
https://code.xinghanlab.com/v1
```

不是：

```text
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 服务与契约验证

```bash
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. 相关文件

主入口与兼容入口：

- [api/agent/router.py](/Users/mac/Projects/agent-manager/tools/agent-manager/api/agent/router.py)
- [api/agnet/router.py](/Users/mac/Projects/agent-manager/tools/agent-manager/api/agnet/router.py)
- [api/swarm/router.py](/Users/mac/Projects/agent-manager/tools/agent-manager/api/swarm/router.py)

状态投影：

- [api/status_projection.py](/Users/mac/Projects/agent-manager/tools/agent-manager/api/status_projection.py)

K8s 部署与配置：

- [k8s/agent-manager-deployment.yaml](/Users/mac/Projects/agent-manager/tools/agent-manager/k8s/agent-manager-deployment.yaml)
- [k8s/agent-manager-configmap.yaml](/Users/mac/Projects/agent-manager/tools/agent-manager/k8s/agent-manager-configmap.yaml)
- [k8s/README.md](/Users/mac/Projects/agent-manager/tools/agent-manager/k8s/README.md)

---

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

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