heicode/docs/integration/普通sub敏捷模式-AgentManager对接任务清单.md

Agent Manager 普通 sub 敏捷模式对接任务清单

更新时间：2026-05-28 发给：Agent Manager 负责人 范围：普通 sub 模式，也就是 Heicode 的普通敏捷开发 Agent 模式。本文不要求 Agent Manager 实现完整蜂群 task graph；蜂群模式另见 蜂群模式-AgentManager对接任务清单.md。

1. 结论

普通 sub 敏捷模式下，Heicode 桌面客户端是用户主体验，Manager 是控制面，Agent Manager 是执行层。

Agent Manager 需要做的是：接收 Manager 生成的 deployment payload，按 sub_mode=agile 和 agile_context 执行阶段化开发，持续把阶段状态、日志、事件、artifact、审批请求、用量和最终结果回传给 Manager。

计费边界：PayPal 只作为 Heicode Manager 未来收款渠道，用于余额充值或购买 Heicode 内部订阅套餐；普通 sub 任务执行中的模型费用仍按 Manager/NewAPI 的钱包余额或订阅额度扣费。Agent Manager 不需要接 PayPal，但必须回传模型用量和运行 usage，方便 Manager/NewAPI 做归属和审计。

普通 sub 不等于蜂群模式：

项	普通 sub 敏捷	蜂群模式
重点	需求、设计、开发、测试、修复、部署等阶段推进	多 Agent 任务图、claim、heartbeat、handoff
是否必须 task graph	否	是
是否需要 artifact 回流	是	是
是否需要高危审批	是	是
是否需要日志/事件/指标	是	是
客户端主体验	是	是

2. 当前 Manager 已完成

能力	状态	说明
HeicodeTask -> deployment draft	已完成	POST /api/agnet/user/tasks/{task_id}/deployment-draft
用户态 deployment 创建	已完成	POST /api/agnet/user/deployments
Runtime create bridge	已完成	通过环境变量调用 Agent Manager
Runtime stop bridge	已完成	停止时同步 Runtime
callback 接收	已完成	POST /api/agnet/callbacks/swarm-events
phase / timeline 聚合	已完成	deployment timeline 聚合 audit、callback、artifact、SK
artifact 查询	已完成	GET /api/agnet/user/deployments/{deployment_id}/artifacts
approval 查询/approve/reject	已完成	/api/agnet/approvals
V2 body 加密	已完成	桌面客户端到 Manager 的 POST 请求复用模型调用加密协议
生产验证	已完成核心链路	生产已验证 Manager 1.4.18 可通过 /api/swarms 创建普通 sub run，持久化 runtime_swarm_id=swm_*，Agent Manager 自动 callback 可写入 events/timeline；1.4.19 补齐 callback 后反写 deployment 快照
callback 状态反写	已完成	Manager 接收 deployment.status_changed、phase.changed、timeline.updated、agent.started/completed/crashed 后，会同步更新 deployment status/phase/runtime_state/agent_instances，避免详情页长期停留 initializing/pending
PayPal/计费边界文档	已完成	docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md 已明确收款、余额、订阅、NewAPI 扣费和 Agent 运行预算关系

3. Agent Manager 需要实现或确认的 P0

任务	必需	原因	验收
接收 Manager 创建请求	是	Manager 会把普通 sub deployment 发送给 Agent Manager	POST /api/agnet/deployments 或配置的 create path 返回 2xx
支持 sub_mode=agile	是	普通敏捷模式核心标识	不认识时不能按蜂群 task graph 强制处理
支持 agile_context	是	用于阶段、检查点、验收标准和下一步动作	Runtime 能读取并在回调里更新 stage/checkpoint
支持阶段状态回传	是	客户端需要知道当前处在需求/设计/开发/测试/修复/部署哪个环节	回调 phase.changed 或 timeline.updated
支持 artifact 回写	是	中间交付物和最终结果必须回到 Heicode	回调 artifact.created
支持审批请求	是	高危操作必须客户端审批	回调 approval.requested 并等待 decision
支持 stop	是	用户停止任务时 Runtime 必须停止真实执行	stop 接口返回 stopped
支持日志/事件/指标	是	联调和验收需要排障数据	提供 callback 或查询接口
支持用量归属	是	NewAPI / CodeGW 计费要按 deployment/task/role 归属	回传 usage/budget 事件或在模型调用中带 correlation
支持 Runtime usage 回传	是	budget.max_cost_usd 只是预算上限，真实 Agent 运行费用不能由 Manager 猜	回传模型 token/cost、runtime 秒数、CPU/内存等可核对 usage

4. Runtime 创建接口

Manager 当前默认 create path：

AGNET_RUNTIME_CREATE_PATH=/api/agnet/deployments

如果 Agent Manager 统一使用 /api/swarms，Manager 也可以配置切过去。但普通 sub 敏捷模式建议先支持：

POST /api/agnet/deployments
Authorization: Bearer <service_token>
X-User-ID: <manager_user_id>
X-Binding-Scope: <binding_scope>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: manager-<manager_deployment_id>
Content-Type: application/json

请求体核心形状：

{
  "orchestration_plan": {
    "intent_id": "task-client-sim-1779875397",
    "template_hint": "heicode-task",
    "objective": "交付轻量待办系统 MVP",
    "sub_mode": "agile",
    "risk_level": "low",
    "budget": {
      "max_tokens": 20000,
      "max_cost_usd": 1,
      "max_duration_sec": 600
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode",
      "binding_scope": "task-client-sim"
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "smoke-model",
      "allowed_model_ids": ["smoke-model"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
    },
    "agile_context": {
      "iteration": "2026-05-28",
      "stage": "planning",
      "checkpoint": "draft_created",
      "acceptance_criteria": [
        "接口返回成功",
        "artifact 可回写到 timeline",
        "不出现明文密钥"
      ],
      "next_action": "continue",
      "requires_user_approval": false
    },
    "agent_runtime": {
      "platform": "agnet",
      "agents": [
        {
          "role": "backend",
          "model_ref": "smoke-model",
          "instance_count": 1
        }
      ]
    },
    "agents": [
      {
        "role_template": "backend",
        "goal": "完成本轮后端任务",
        "default_model_id": "smoke-model",
        "resource_grants": []
      }
    ],
    "resource_grants": []
  },
  "agents": [
    {
      "role": "backend",
      "resource_grants": []
    }
  ],
  "risk_level": "low",
  "budget": {
    "max_tokens": 20000,
    "max_cost_usd": 1,
    "max_duration_sec": 600
  },
  "billing_context": {
    "provider": "newapi",
    "default_model_id": "smoke-model",
    "allowed_model_ids": ["smoke-model"],
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
  },
  "resource_grants": [
    {
      "grant_id": "grant-client-sim-git",
      "resource_id": "git-client-sim",
      "resource_type": "git",
      "permission_scope": ["repo:read"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/client-sim-git",
      "ref": "azkv://heicode-kv.vault.azure.net/secrets/client-sim-git",
      "target_role": "backend"
    }
  ],
  "callback": {
    "url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
    "subscribed_events": [
      "deployment.status_changed",
      "phase.changed",
      "agent.started",
      "agent.completed",
      "agent.crashed",
      "sk_tool.called",
      "sk_tool.completed",
      "sk_tool.failed",
      "approval.requested",
      "budget.alert",
      "artifact.created",
      "timeline.updated"
    ]
  },
  "agile_context": {
    "iteration": "2026-05-28",
    "stage": "planning",
    "checkpoint": "draft_created",
    "next_action": "continue",
    "requires_user_approval": false
  },
  "sub_mode": "agile",
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_deployment_id": "dep_xxx",
    "heicode_runtime_bridge": true,
    "correlation_id": "corr_xxx"
  }
}

响应：

{
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "status": "running",
    "estimated_ready_at": "2026-05-28T10:02:00Z"
  }
}

建议也返回 swarm_id，即使普通 sub 不强依赖蜂群任务图，后续统一追踪会更方便。

5. 普通 sub 敏捷阶段

Agent Manager 至少要支持以下阶段语义，并通过 callback 回写当前阶段：

stage	含义	建议 checkpoint
planning	需求澄清/任务拆分	draft_created, requirements_confirmed
design	方案/API/数据结构设计	design_ready
development	编码实现	backend_done, frontend_done, artifact_ready
testing	自动测试/手工验证	ready_for_test, test_passed, test_failed
fixing	根据测试或用户反馈修复	fix_started, fix_ready
deployment	部署/发布准备	deploy_ready, deployed
review	复核/总结/交付	review_ready, completed
done	结束	completed
failed	失败	failed

阶段回调示例：

{
  "event_id": "evt_phase_1",
  "event_type": "phase.changed",
  "deployment_id": "dep_xxx",
  "agent_instance_id": "agent-backend-1",
  "occurred_at": "2026-05-28T10:10:00Z",
  "correlation_id": "corr_xxx",
  "source": "agent-manager",
  "payload": {
    "stage": "development",
    "checkpoint": "backend_done",
    "title": "后端实现完成",
    "summary": "已完成工单列表和状态流转接口，等待测试",
    "agent_role": "backend",
    "severity": "success",
    "next_action": "submit_test_result"
  }
}

如果 Agent Manager 暂时不支持 phase.changed，也可以先使用 timeline.updated，但 payload 中必须带 stage 和 checkpoint。

6. timeline.updated

普通 sub 敏捷下，客户端主要看 timeline。Agent Manager 应持续回写可展示事件。

联调前可以先请求 Manager 当前接受的 callback schema：

GET https://code.xinghanlab.com/api/agnet/callbacks/swarm-events/schema

该接口只返回事件类型、分类和必填字段，不返回任何 token 或密钥。普通 sub 敏捷重点核对 phase.changed、timeline.updated、artifact.created、approval.requested、sk_tool.* 和 budget.alert。

{
  "event_id": "evt_timeline_1",
  "event_type": "timeline.updated",
  "deployment_id": "dep_xxx",
  "occurred_at": "2026-05-28T10:11:00Z",
  "source": "agent-manager",
  "payload": {
    "title": "测试完成",
    "summary": "接口测试通过 12 项，未发现阻塞问题",
    "stage": "testing",
    "checkpoint": "test_passed",
    "agent_role": "reviewer",
    "severity": "success",
    "next_action": "submit_artifact"
  }
}

7. artifact.created

普通 sub 模式必须回流中间交付物和最终交付结果。不要只写 Runtime 本地日志。

{
  "event_id": "evt_artifact_1",
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "task_id": "task-backend-1",
  "source": "agent-manager",
  "payload": {
    "artifact_id": "art_test_report_1",
    "artifact_type": "test_report",
    "title": "接口测试报告",
    "summary": "12 项接口测试通过",
    "uri": "artifact://runtime/dep_xxx/test-report",
    "checksum": "sha256:abc123",
    "stage": "testing",
    "checkpoint": "test_passed"
  }
}

支持的 artifact_type 建议：

artifact_type	说明
code_patch	代码补丁或分支引用
document	需求/设计/说明文档
test_report	测试报告
deployment_manifest	部署清单
log_bundle	日志包
other	其他

8. approval.requested 和 decision

普通 sub 模式也需要高危审批。高危动作包括但不限于：

操作	例子
写 Git 仓库	push 分支、改配置、创建 PR
改云资源	创建/删除 VM、AKS、存储、数据库
部署到生产	发布、迁移、重启服务
使用敏感凭据	需要从 secret_ref 派生短期凭证

审批请求：

{
  "event_id": "evt_approval_1",
  "event_type": "approval.requested",
  "deployment_id": "dep_xxx",
  "agent_instance_id": "agent-backend-1",
  "source": "agent-manager",
  "payload": {
    "approval_id": "appr_runtime_1",
    "operation": "git.write",
    "resource_id": "repo-main",
    "resource_type": "git",
    "resource_scope": "feature/*",
    "target_role": "backend",
    "risk_level": "high",
    "requires_credential": true,
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
    "ttl_seconds": 900,
    "reason": "需要写入功能分支以提交本轮修改"
  }
}

Manager 回传 decision：

POST /api/swarms/{swarm_id}/approvals/{approval_id}

如果普通 sub 不使用 swarm_id，可让 Manager 配置为：

AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/agnet/deployments/{deployment_id}/approvals/{approval_id}

Runtime 需要接收：

{
  "approval_id": "appr_runtime_1",
  "decision": "approved",
  "manager_deployment_id": "dep_xxx",
  "runtime_deployment_id": "runtime-dep-123",
  "operation": "git.write",
  "resource_id": "repo-main",
  "resource_type": "git",
  "target_role": "backend",
  "requires_credential": true,
  "credential_ref": "lease://agnet/lease_xxx",
  "lease_id": "lease_xxx",
  "lease_expires_at": 1779850900000
}

Runtime 收到：

decision	Runtime 动作
approved	继续该高危动作，只使用 credential_ref 对应的短期凭证
rejected	停止该动作，回调 timeline.updated 或 phase.changed，标记被拒绝

9. logs / events / metrics

Manager 当前有用户态查询位置，但真实数据需要 Agent Manager 产出。

Agent Manager 至少需要支持以下一种方式：

方式	说明
callback 摘要	用 timeline.updated 持续回写阶段、耗时、错误摘要
查询接口	提供 /logs、/events、/metrics，Manager 后续可拉取
混合	关键状态 callback，详细日志走查询接口

建议指标：

指标	用途
status	running/stopped/failed/completed
stage / checkpoint	当前敏捷阶段
agent_role	哪个角色在执行
tokens_used / cost_usd	用量归属
duration_ms	阶段耗时
error_code / error_message	失败排障
artifact_count	产物数量

10. billing / NewAPI 用量归属

Agent Manager 调模型时，需要把 Manager 传入的上下文带上，便于 NewAPI / CodeGW 计费归属。

PayPal 不在这条链路里。PayPal 支付成功后只会把用户权益写入 Heicode 钱包余额或内部订阅；普通 sub 执行时，Agent Manager 仍然按 billing_context.provider=newapi 使用 Manager 传入的用户、deployment、role 和模型上下文。

至少保留：

字段	来源	用途
user_id	user_context.user_id	用户归属
manager_deployment_id	metadata.manager_deployment_id	deployment 归属
correlation_id	header 或 metadata	链路追踪
agent_role	agents[].role	角色归属
task_id	Runtime 内部任务	子任务归属
model_id	billing/default model	模型用量

Agent Manager 回传 usage 时建议至少包含：

字段	说明
model_tokens	本 deployment/task/role 消耗的模型 token。
model_cost_usd	Runtime 或 NewAPI 可确认的模型成本。
runtime_seconds	Agent 实际运行秒数。
cpu_core_seconds	如 Runtime 具备集群指标，应回传 CPU 使用量。
memory_mb_seconds	如 Runtime 具备集群指标，应回传内存使用量。
billing_source	建议为 newapi、manager_wallet、manager_subscription 或 Runtime 约定值。

注意：budget.max_tokens、budget.max_cost_usd、budget.max_duration_sec 是预算和拦截上限，不是已结算金额。Manager 只能展示和审计预算；真实扣费或成本归属必须基于 Agent Manager / Runtime 回传的 usage。

如果发生预算告警，回调：

{
  "event_id": "evt_budget_1",
  "event_type": "budget.alert",
  "deployment_id": "dep_xxx",
  "source": "agent-manager",
  "payload": {
    "consumed_usd": 7.2,
    "max_cost_usd": 8,
    "threshold_pct": 90,
    "severity": "warning"
  }
}

11. 安全要求

要求	说明
不接收/不打印明文长期密钥	password/token/private_key/access_key/connection_string/model key 都不能出现在日志、callback、artifact metadata
只使用 secret_ref	长期凭据引用统一 azkv://<vault>/secrets/<name>
只用 credential_ref 执行审批后的动作	Manager 同意后返回 lease://...，不要要求长期密钥
callback 必须幂等	重试同一个 event_id 不能重复创建 artifact/approval
callback 必须有来源	source=agent-manager 或 heicode-swarm-runtime

12. 普通 sub 联调验收步骤

步骤	操作	期望
1	Manager 调 Agent Manager health	healthy
2	Manager 创建 sub_mode=agile deployment	Runtime 返回 deployment_id，建议返回 swarm_id
3	Runtime 回调 phase.changed planning/design/development/testing	Manager timeline 可见阶段推进
4	Runtime 回调 timeline.updated	客户端可展示当前子环节反馈
5	Runtime 回调 artifact.created	Manager artifacts 列表出现中间产物
6	Runtime 回调 approval.requested	Manager pending approval 出现
7	Manager approve/reject	Runtime 收到 decision 并继续/停止对应动作
8	Manager stop	Runtime deployment 真实停止
9	Runtime 回调 completed/failed	Manager detail/timeline 显示终态
10	Runtime 回调用量	Manager 能看到 model token/cost 或 usage 摘要，且与 deployment/task/role/correlation 关联
11	查日志	不出现明文密钥，不丢 correlation_id
12	生产路由复核	GET /api/agnet/callbacks/swarm-events/schema 返回 200，用户态/后台态接口使用有效登录态通过 smoke

13. Agent Manager 不需要处理的内容

不需要处理	原因
桌面客户端 V2 body 加密	这是客户端到 Manager，Manager 已处理
Manager 用户登录/session	Manager 控制
HeicodeTask 追问/任务卡生成	客户端和 Manager 代理处理
Azure Key Vault 写入长期密钥	Manager 负责资源绑定和 secret_ref 管理
Web 控制台页面展示	Manager 负责
PayPal 收款和充值订单	Manager 负责；Agent Manager 只需要回传执行和用量，不直接处理支付

14. 当前已知缺口

缺口	属于谁	说明
真实 Runtime 是否完整消费 agile_context	Agent Manager	需要确认字段被使用，不只是透传
阶段状态持续回传	Agent Manager	当前 Manager 有接收能力，缺真实数据
artifact 真实产出	Agent Manager	需要 Runtime 输出 Git/存储/报告 URI
approval decision 接收路径	Agent Manager + Manager 配置	需确认最终路径是 /api/swarms/... 还是 /api/agnet/deployments/...
用量回传	Agent Manager + NewAPI/CodeGW	需要按 user/deployment/task/role 归属
Agent 运行费用真实结算	Agent Manager + Manager	当前 Manager 有预算字段和文档口径，缺 Runtime 真实 usage，不能只按预算估算扣费
生产 callback schema 路由	Manager 部署/路由	本地代码和测试已覆盖，2026-05-28 生产公开访问 /api/agnet/callbacks/swarm-events/schema 返回 404，需要重新上线或核对生产镜像/路由
无 body GET 的 V2 签名	客户端 + Manager	这是客户端全链路无 cookie 的后续项，不阻塞 Agent Manager 创建/回调联调