# Heicode Sub Mode Runtime 对接指南

更新时间：2026-06-01

本文档是给 **Manager / 客户端 / 平台接入方** 的 sub mode 对接指南。目标不是解释历史背景，而是让别人能够基于本文档直接接通当前仓库提供的 **Sub Agile / 普通 sub 模式 Runtime**。

## 1. 先记结论

当前仓库只负责：

- `sub_agile` / 普通 sub 模式 Runtime

当前仓库不负责：

- 真正的 Swarm 产品模式
- 独立的 swarm-only API

命名约定：

- `agent`：主命名，新的标准入口
- `agnet`：兼容命名，旧调用方继续可用
- `/api/swarms`：仅是 sub-mode compatibility API，不代表当前仓库实现独立 swarm 产品

推荐接入原则：

1. 新接入统一走 `/api/agent/*`
2. 旧系统暂时可继续走 `/api/agnet/*`
3. 只有历史 Runtime 兼容方才使用 `/api/swarms`

## 2. 推荐接法

### 2.1 健康检查

主路径：

```text
GET /api/agent/health
```

兼容路径：

```text
GET /api/agnet/health
```

返回示例：

```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "agent-manager-sub-mode-runtime",
    "version": "1.0.0",
    "phase": "sub-mode-runtime"
  }
}
```

### 2.2 创建 deployment

主路径：

```text
POST /api/agent/sub-agile/deployments
```

兼容路径：

```text
POST /api/agnet/deployments
```

Runtime 兼容创建路径：

```text
POST /api/swarms
```

如果你是新接入方，优先使用：

```text
POST /api/agent/sub-agile/deployments
```

### 2.3 查询状态

主路径：

```text
GET /api/agent/sub-agile/deployments/{deployment_id}
```

兼容路径：

```text
GET /api/agnet/deployments/{deployment_id}
GET /api/swarms/{swarm_id}
GET /api/swarms/{swarm_id}/status
```

### 2.4 停止与审批

主路径：

```text
POST /api/agent/sub-agile/deployments/{deployment_id}/stop
POST /api/agent/sub-agile/deployments/{deployment_id}/approvals/{approval_id}
```

兼容路径：

```text
POST /api/agnet/deployments/{deployment_id}/stop
POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
POST /api/swarms/{swarm_id}/stop
POST /api/swarms/{swarm_id}/approvals/{approval_id}
```

### 2.5 读取产物

推荐路径：

```text
GET /api/agent/user/deployments/{deployment_id}/artifacts
GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
```

兼容路径：

```text
GET /api/agnet/user/deployments/{deployment_id}/artifacts
GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content
```

## 3. 状态语义

当前对外统一投影为以下状态：

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

含义建议：

- `accepted`：Runtime 已接单，尚未进入明确执行态
- `running`：至少有一个 subagent 正在执行
- `waiting_approval`：Runtime 请求用户审批，等待 decision
- `completed`：任务完成，并且已经有终态结果或产物
- `failed`：执行失败
- `stopped`：被显式停止

注意：

- 新创建 deployment 默认返回 `accepted`
- `approval.requested` 会把展示状态投影为 `waiting_approval`
- `/api/swarms` 虽然内部复用旧表和旧 runtime 记录，但对外也返回同一套状态集合

## 4. 推荐请求结构

### 4.1 新接入推荐请求

推荐你用结构化 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"]
      },
      {
        "role": "frontend",
        "template": "a2a_litellm_agent",
        "model": "gpt-5.4",
        "capabilities": ["ui", "react", "css"]
      }
    ]
  },
  "callback": {
    "url": "https://your-manager.example.com/api/agent/callbacks/runtime-events"
  }
}
```

### 4.2 最低必填项

如果走 `/api/swarms` 兼容入口，最低要求至少要有：

- `orchestration_plan`
- `orchestration_plan.sub_mode`
- `orchestration_plan.user_context.user_id`
- `callback.url`

否则会返回 `422`

## 5. 创建响应与查询响应

### 5.1 创建响应示例

```json
{
  "deployment_id": "swm_xxx",
  "swarm_id": "swm_xxx",
  "status": "accepted",
  "agents": [
    {
      "agent_id": "agi_backend_xxx",
      "role": "backend",
      "status": "pending",
      "namespace": "swarm-swm-xxxx-backend",
      "service_url": "http://agent-....svc.cluster.local:8000"
    }
  ],
  "created_at": "2026-06-01T12:00:00Z",
  "estimated_ready_at": "2026-06-01T12:02:00Z"
}
```

字段说明：

- `deployment_id`：对外主标识
- `swarm_id`：仅为兼容字段；当前通常与 `deployment_id` 相同
- `agents`：当前 runtime 里为本次执行创建的 subagent 实例

### 5.2 状态响应示例

```json
{
  "deployment_id": "swm_xxx",
  "swarm_id": "swm_xxx",
  "status": "completed",
  "phase": "development",
  "progress": 100,
  "agents": [
    {
      "agent_id": "agi_backend_xxx",
      "role": "backend",
      "status": "completed",
      "output": "后端实现摘要..."
    }
  ],
  "metrics": {
    "total_messages": 4,
    "tokens_used": 1514,
    "elapsed_seconds": 33
  },
  "artifacts": [
    {
      "artifact_id": "art_xxx_backend_1",
      "artifact_type": "code_patch",
      "title": "backend task delivery",
      "summary": "后端实现摘要...",
      "uri": "azblob://...",
      "metadata": {
        "runtime_deployment_id": "swm_xxx",
        "download_path": "/api/swarms/swm_xxx/artifacts/art_xxx_backend_1/content"
      }
    }
  ]
}
```

## 6. 回调事件

### 6.1 主回调入口

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

### 6.2 兼容回调入口

```text
POST /api/agnet/callbacks/swarm-events
```

### 6.3 当前支持的关键事件

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

### 6.4 接入建议

对接方至少应该消费：

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

如果你只做最小接入，这四类事件足够支撑：

- 状态展示
- 阶段进度
- 产物列表刷新
- 审批按钮展示

## 7. 产物读取约定

### 7.1 推荐读取顺序

推荐按照这个顺序读取结果：

1. 查询 deployment 状态
2. 等待 `status=completed`，或者在 `artifacts` 不为空时提前读取
3. 调用 artifacts list 接口获取 `artifact_id`
4. 再通过 content 接口拉完整正文

### 7.2 synthesized fallback artifact

如果真实 agent 没有产出具体 artifact，runtime 会生成 fallback artifact。

约定：

- fallback artifact 仍然会出现在 artifacts 列表中
- 它的用途是让 Manager 和客户端至少有一个可展示终态结果
- 识别方式是：

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

## 8. 真实联调建议

这是本次线上验证后的建议，不是理论建议。

### 8.1 当前稳定范围

当前 runtime 对以下任务更稳定：

- 小型单文件函数生成
- 小型 React 组件生成
- 中小型实现摘要 / 代码骨架任务

### 8.2 当前不稳定范围

当前 runtime 在以下任务上可能失败：

- 单次 prompt 很长的真实开发任务
- 要求一次性输出大段后端 + 前端 + reviewer 的任务
- 输出内容过大、tokens 较高的代码生成任务

实际线上现象：

- 较大的真实编程任务可能在模型网关返回 `504 Gateway Time-out`

### 8.3 推荐任务拆分方式

为了让 sub mode 更稳定，建议把一个大任务拆成多个小任务，例如：

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

不要一上来就发：

- “生成完整后端项目”
- “生成完整前后端联调代码”
- “一次性给出所有页面、接口、测试和审查报告”

## 9. 模型网关配置要求

这是当前最容易踩坑的地方。

当前 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`

## 10. 最小验证流程

### 10.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
```

### 10.2 真实 smoke 验证

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

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

成功标准：

1. 创建响应返回 `accepted`
2. 最终状态到 `completed`
3. `artifacts` 非空
4. `artifacts/{artifact_id}/content` 返回可读正文，而不是 UUID、HTML 或空串

## 11. 相关文件

主入口与兼容入口：

- [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. 新接入统一走 `/api/agent/sub-agile/*`
2. 结果读取统一走 `deployment_id -> artifacts -> artifact content`
3. 模型网关基址必须是 `https://code.xinghanlab.com/v1`