feat(agent): unify agnet→agent and implement client/runtime unification spec v0.1 core

按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。

命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
  结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
  DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。

统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
  completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。

验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/integration/agent-platform-request-contract.md

@@ -0,0 +1,961 @@
+# Manager → Agent 平台接口参数文档
+
+**版本**: v0.3（P1/P5 联调契约）
+**生效日期**: 2026-05-03
+**状态**: 联调准备；当前仓库提供 Manager 侧最小验证端点，生产 Agent 平台部署尚未在本文档中宣称完成。
+**方向**: Heicode Manager 主动请求 Agent 平台；Agent 平台返回部署、日志、监控与审计状态。
+**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志，以及 Agent 辅助 NewAPI 重建/部署的参数约定。
+
+> 2026-05-04 边界修正：Manager 当前不把 `tenant/project` 作为产品、认证或扣费主轴。新请求应使用 `user_context.user_id`、`user_context.channel_id`、`resource_grants[].binding_scope`、`billing_context(newapi)` 和 `agent_runtime(agent)`。本文中仍出现的 `tenant_id/project_id` 只表示旧字段兼容或历史接口命名，不应作为新功能设计依据。
+**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`/环境变量名；不得传明文密码、Token、私钥、连接串或云访问密钥。
+
+> 本文档描述 Manager 对 Agent 平台的出站集成契约。当前仓库中 `/api/agent/*` 是 Manager 侧最小控制面/模拟端点，用于校验同一套 payload 结构；生产接入时，Manager 应将下列请求发送到 Agent 平台网关。
+
+## 0. 概述
+
+本文档按登录接口文档的对接方式组织：先定义接入信息，再逐个接口给出请求、响应、错误和安全约束。接口分组如下：
+
+| 接口 | 用途 | 当前性质 |
+|---|---|---|
+| `POST /api/agent/deployments` | 创建子 Agent/运维任务部署，含 NewAPI 重建/部署场景 | 必需 |
+| `GET /api/agent/deployments` | 查询部署列表 | 必需 |
+| `GET /api/agent/deployments/{deployment_id}` | 查询单个部署详情 | 必需 |
+| `POST /api/agent/deployments/{deployment_id}/stop` | 停止部署或取消排队任务 | 必需 |
+| `GET /api/agent/deployments/{deployment_id}/logs` | 拉取部署日志 | 必需 |
+| `GET /api/agent/deployments/{deployment_id}/logs/stream` | 实时日志 SSE | 可选 |
+| `GET /api/agent/projects/{project_id}/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容，参数值按 `binding_scope` 解释 | 必需 |
+| `GET /api/agent/deployments/{deployment_id}/metrics` | 单部署指标序列 | 建议 |
+| `GET /api/agent/deployments/{deployment_id}/events` | 部署事件 | 必需 |
+| `GET /api/agent/audit-logs` | 审计日志 | 必需 |
+| `POST /api/agent/sk-snapshots/resolve` | 触发 SK 快照解析 | 必需 |
+| `GET /api/agent/deployments/{deployment_id}/sk-snapshots` | 查询 SK 快照 | 必需 |
+
+> 不在本文档范围：真实 Secret Store 写入、生产 SSH 登录、云账号授权回调、NewAPI 管理后台开放。生产部署动作只有实际执行并通过日志/监控/审计验证后，才能在报告中标记为“已部署”。
+
+---
+
+## 1. 接入约定
+
+### 1.1 Base URL
+
+由部署环境配置，不写入仓库。例如：
+
+```text
+AGENT_PLATFORM_BASE_URL=https://agent-platform.example.com
+```
+
+联调环境建议使用独立域名或内网网关，示例不得包含真实凭据：
+
+```text
+AGENT_PLATFORM_BASE_URL=https://staging-agent.example.com
+MANAGER_SERVICE_TOKEN_SECRET_REF=azkv://heicode-kv.vault.azure.net/secrets/manager-service-agent-platform-service-token
+```
+
+完整路径示例：
+
+```http
+POST https://agent-platform.example.com/api/agent/deployments
+```
+
+### 1.2 通用 Header
+
+| Header | 必填 | 说明 |
+|---|---:|---|
+| `Authorization: Bearer <manager-service-token>` | 是 | Manager 服务身份令牌，由 Secret Store/运行环境注入。 |
+| `Content-Type: application/json` | POST/PUT 是 | JSON 请求体。 |
+| `X-User-Id: <user_id>` | 建议 | 登录用户边界；也可从 Manager 服务端 token 或 body `user_context.user_id` 推导。 |
+| `X-Binding-Scope: <binding_scope>` | 建议 | Git/SK/云资源作用域；也可从 `resource_grants[].binding_scope` 推导。 |
+| `X-Correlation-Id: <uuid>` | 是 | Manager 生成，全链路追踪。 |
+| `X-Request-Id: <uuid>` | 建议 | 单次 HTTP 请求追踪 ID，可与 correlation_id 不同。 |
+| `Idempotency-Key: <uuid>` | 创建类接口建议 | 避免重试造成重复部署。 |
+
+### 1.3 通用响应包裹
+
+成功：
+
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+失败：
+
+```json
+{
+  "success": false,
+  "message": "human readable message",
+  "error": {
+    "code": "POLICY_REJECTED",
+    "message": "human readable message",
+    "request_id": "req_xxx"
+  }
+}
+```
+
+建议错误码：
+
+| code | 场景 |
+|---|---|
+| `POLICY_REJECTED` | 缺必填字段、权限策略不满足、风险等级非法。 |
+| `BUDGET_EXCEEDED` | 超过 token/金额/时长预算。 |
+| `MODEL_NOT_ALLOWED` | agent 默认模型不在允许列表内。 |
+| `FORBIDDEN_SCOPE` | Header 与 body/query 的用户或资源作用域不一致。 |
+| `RESOURCE_GRANT_INVALID` | Resource Grant 字段缺失、跨用户/跨资源作用域/角色不匹配。 |
+| `RESOURCE_GRANT_SECRET_REF_REQUIRED` | 凭据型资源缺少 `secret_ref`。 |
+| `RESOURCE_GRANT_SECRET_REJECTED` | 请求中出现明文密钥字段。 |
+| `SK_SOURCE_UNRESOLVABLE` | SK 来源不可解析。 |
+| `DEPLOYMENT_CONFLICT` | 部署不存在、状态冲突或重复提交。 |
+| `NOT_FOUND` | deployment、agent instance、snapshot 或审计资源不存在。 |
+| `CURSOR_EXPIRED` | 分页游标过期或不属于当前查询条件。 |
+| `RATE_LIMITED` | 平台限流；响应头建议包含 `Retry-After`。 |
+| `INTERNAL_ERROR` | 平台内部错误；Manager 应记录 request_id 并重试或提示稍后处理。 |
+
+### 1.4 通用错误处理
+
+| HTTP | business code | Manager 处理建议 |
+|---:|---|---|
+| 400 | `POLICY_REJECTED` / `RESOURCE_GRANT_INVALID` | 标记部署失败，展示校验原因，不自动重试。 |
+| 401 | `UNAUTHORIZED` | 检查 Manager 服务令牌的 `secret_ref`/环境注入，不把令牌写入日志。 |
+| 403 | `FORBIDDEN_SCOPE` / `MODEL_NOT_ALLOWED` | 阻断本次部署，写审计事件。 |
+| 404 | `NOT_FOUND` | 对查询类接口返回空态；对控制类接口提示资源不存在。 |
+| 409 | `DEPLOYMENT_CONFLICT` | 使用 `Idempotency-Key` 查询既有结果，避免重复创建。 |
+| 410 | `CURSOR_EXPIRED` | 丢弃 cursor，使用 `since` 重新拉取。 |
+| 422 | `RESOURCE_GRANT_SECRET_REF_REQUIRED` / `RESOURCE_GRANT_SECRET_REJECTED` | 要求 Manager 重新生成只含 `secret_ref` 的 payload。 |
+| 429 | `RATE_LIMITED` | 按 `Retry-After` 退避重试。 |
+| 500/503 | `INTERNAL_ERROR` | 指数退避重试；超过阈值后转人工排查。 |
+
+---
+
+## 2. 创建子 Agent 部署
+
+### 2.1 Endpoint
+
+```http
+POST /api/agent/deployments
+```
+
+### 2.2 请求体
+
+```json
+{
+  "orchestration_plan": {
+    "intent_id": "intent_20260502_001",
+    "template_hint": "manager-resource-binding",
+    "objective": "为已绑定的代码仓库启动 builder 子 Agent，允许其读取 SK 并在限定路径内提交代码",
+    "risk_level": "low",
+    "budget": {
+      "max_tokens": 100000,
+      "max_cost_usd": 30,
+      "max_duration_sec": 7200
+    },
+    "user_context": {
+      "user_id": "user_123",
+      "email": "user@example.com",
+      "role": "user",
+      "channel_id": "channel_abc",
+      "subscription_tier": "pro"
+    },
+    "billing_context": {
+      "provider": "newapi",
+      "newapi_user_ref": "newapi_user_123",
+      "newapi_group": "development",
+      "quota_ref": "newapi_token_or_group_quota_ref"
+    },
+    "agent_runtime": {
+      "platform": "agent",
+      "agents": [
+        {
+          "role": "builder",
+          "model_ref": "agent_model_profile_builder",
+          "instance_count": 1
+        }
+      ]
+    },
+    "constraints": {
+      "allowed_model_ids": ["gpt-5.4-mini", "gpt-5.4"]
+    },
+    "metadata": {
+      "tenant_id": "legacy-user-scope",
+      "project_id": "legacy-resource-scope",
+      "correlation_id": "corr_20260502_001"
+    },
+    "agents": [
+      {
+        "role_template": "builder",
+        "goal": "按 Manager 下发的任务在允许资源内完成实现、验证并回传状态",
+        "default_model_id": "gpt-5.4-mini",
+        "sk_sources": [
+          {
+            "type": "git",
+            "mime": "text/markdown",
+            "repo_ref": {
+              "connection_id": "conn_sk_repo_001",
+              "repo_url": "https://example.com/org/sk-repo.git",
+              "ref": "main",
+              "paths": ["skills/heicode/**", "AGENTS.md"]
+            }
+          }
+        ],
+        "runtime_execution": {
+          "profile_id": "aks-codex-standard",
+          "cloud_principal_refs": ["principal://users/user_123/agent-runtime"],
+          "network_policy_ref": "netpol://bindings/repo_default/restricted-egress"
+        },
+        "sk_access_policy": {
+          "policy_ref": "sk-policy://bindings/repo_default/default-readonly",
+          "deny_skill_ids": ["dangerous-shell"],
+          "inherit_deployment_defaults": true
+        },
+        "resource_grants": [
+          {
+            "grant_id": "grant_git_repo_001",
+            "resource_id": "res_git_repo_001",
+            "resource_type": "git",
+            "user_id": "user_123",
+            "binding_scope": "repo_default",
+            "tenant_id": "legacy-user-scope",
+            "project_id": "legacy-resource-scope",
+            "target_role": "builder",
+            "target_agent_ref": "agent-builder-1",
+            "permission_scope": ["repo:read", "repo:write:current-branch"],
+            "constraints": {
+              "ref": "main",
+              "allowed_paths": "heicode/**,docs/**",
+              "forbid_branch_create": "true"
+            },
+            "metadata": {
+              "provider": "gitee",
+              "repo_url": "https://example.com/org/repo.git"
+            },
+            "status": "active",
+            "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/user-123-repo-default-res-git-repo-001",
+            "audit": {
+              "created_by": "manager",
+              "approval_id": "approval_001"
+            }
+          },
+          {
+            "grant_id": "grant_doc_001",
+            "resource_id": "res_project_doc_001",
+            "resource_type": "project_doc",
+            "user_id": "user_123",
+            "binding_scope": "repo_default",
+            "tenant_id": "legacy-user-scope",
+            "project_id": "legacy-resource-scope",
+            "target_role": "builder",
+            "target_agent_ref": "agent-builder-1",
+            "permission_scope": ["doc:read"],
+            "constraints": {
+              "doc_paths": "docs/heicode.md,docs/plan.md"
+            },
+            "metadata": {
+              "doc_ref": "project-doc://project-a/docs-mainline"
+            },
+            "status": "active",
+            "audit": {
+              "created_by": "manager"
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 2.3 字段说明
+
+#### orchestration_plan
+
+| 字段 | 类型 | 必填 | 约束/说明 |
+|---|---|---:|---|
+| `intent_id` | string | 是 | Manager 侧意图 ID，用于幂等、审计和追踪。 |
+| `template_hint` | string | 是 | Agent 平台选择编排模板的提示，如 `manager-resource-binding`。 |
+| `objective` | string | 是 | 本次部署目标，应是自然语言但不能含密钥。 |
+| `risk_level` | enum | 是 | `low` / `medium` / `high`。高风险必须携带客户端审批证据；缺失或不匹配时只能只读或拒绝执行。 |
+| `budget.max_tokens` | int | 是 | 当前策略上限建议不超过 `500000`。 |
+| `budget.max_cost_usd` | number | 是 | 当前策略上限建议不超过 `200`。 |
+| `budget.max_duration_sec` | int | 是 | 当前策略上限建议不超过 `86400`。 |
+| `user_context` | object | 建议 | 登录用户上下文，优先使用 Heicode/Agent 登录返回的 `user.id`/`channelId`。 |
+| `billing_context` | object | 条件 | NewAPI 扣费上下文；只表达 user/token/group/quota 映射，不表达子 Agent 模型或实例数。 |
+| `agent_runtime` | object | 条件 | Agent 平台运行时上下文；表达子 Agent 角色、模型 profile 和实例数，不承载 NewAPI key 或扣费对象。 |
+| `constraints.allowed_model_ids` | string[] | 否 | agent 的 `default_model_id` 如填写，必须在此列表内。 |
+| `metadata.tenant_id` | string | 否 | 旧兼容字段；新实现不得作为产品租户边界。 |
+| `metadata.project_id` | string | 否 | 旧兼容字段；新实现不得作为项目账本边界。 |
+| `metadata.correlation_id` | string | 是 | 全链路追踪 ID。 |
+| `agents` | array | 是 | 至少 1 个子 Agent。 |
+
+#### user_context / billing_context / agent_runtime
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `user_context.user_id` | string | 建议 | Manager 业务用户 ID，来自登录接口 `id` 或 JWT `sub`。 |
+| `user_context.channel_id` | string | 建议 | 用于关联 NewAPI 用户、Token、Group、余额或额度策略。 |
+| `billing_context.provider` | enum | 条件 | 当前只允许 `newapi`。设置后必须提供 `channel_id`、`newapi_user_ref`、`newapi_group` 或 `quota_ref` 之一。 |
+| `billing_context.newapi_user_ref` | string | 否 | NewAPI 用户映射引用，不是 NewAPI key。 |
+| `billing_context.newapi_group` | string | 否 | NewAPI Group 映射，用于额度或策略选择。 |
+| `billing_context.quota_ref` | string | 否 | Token 或 Group 额度引用，不得包含真实 Token 原文。 |
+| `agent_runtime.platform` | enum | 条件 | 当前只允许 `agent`。 |
+| `agent_runtime.agents[].role` | string | 条件 | 必须匹配 `agents[].role_template`。 |
+| `agent_runtime.agents[].model_ref` | string | 条件 | Agent 平台模型 profile 引用；不是 NewAPI 扣费字段。 |
+| `agent_runtime.agents[].instance_count` | int | 条件 | 子 Agent 实例数量，必须大于 0。 |
+
+#### agents[]
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `role_template` | string | 是 | 平台角色模板，如 `builder`/`reviewer`/`operator`。 |
+| `goal` | string | 是 | 此 agent 的任务目标。 |
+| `default_model_id` | string | 否 | 默认模型；若设置需满足 allowed_model_ids。 |
+| `sk_sources` | array | 否 | SK 来源，平台应解析为只读快照。 |
+| `runtime_execution` | object | 否 | 运行环境绑定；任一字段存在时 `profile_id` 必填。 |
+| `sk_access_policy` | object | 否 | SK 权限策略。若 `deny_skill_ids` 非空，需 `policy_ref` 或继承默认策略。 |
+| `resource_grants` | array | 否 | Manager 下发给子 Agent 的最小权限资源授权。 |
+
+#### sk_sources[]
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `type` | enum | 否 | 空值表示不启用；支持 `git`、`upload`。 |
+| `artifact_id` | string | upload 必填 | 上传型 SK 包 ID。 |
+| `mime` | string | 否 | 内容类型，如 `text/markdown`。 |
+| `repo_ref.connection_id` | string | git 建议 | Git 连接资源 ID。 |
+| `repo_ref.repo_url` | string | git 建议 | 仓库 URL；不得带用户名密码。 |
+| `repo_ref.ref` | string | git 必填 | 分支/标签/commit。 |
+| `repo_ref.paths` | string[] | git 必填 | 允许读取的路径。 |
+
+#### runtime_execution
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `profile_id` | string | 条件必填 | Agent 平台运行规格，如 AKS profile。 |
+| `cloud_principal_refs` | string[] | 否 | 运行身份引用，不是明文凭据。 |
+| `network_policy_ref` | string | 否 | 网络策略引用，用于限制出站/入站。 |
+
+#### resource_grants[]
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `grant_id` | string | 是 | 授权记录 ID。 |
+| `resource_id` | string | 是 | Manager 资源 ID。 |
+| `resource_type` | enum | 是 | `git` / `sk` / `project_doc` / `cloud_account` / `cloud_resource`。 |
+| `user_id` | string | 建议 | 与 `user_context.user_id` 一致；为空时平台可从部署上下文推导。 |
+| `binding_scope` | string | 是 | Git/SK/云资源作用域，例如 repo/ref/path 或云资源引用。 |
+| `tenant_id` | string | 否 | 旧兼容字段；新实现不应依赖。 |
+| `project_id` | string | 否 | 旧兼容字段；新实现不应依赖。 |
+| `target_role` | string | 是 | 必须等于当前 agent 的 `role_template`。 |
+| `target_agent_ref` | string | 是 | Manager 侧对子 Agent 的逻辑引用。 |
+| `permission_scope` | string[] | 是 | 最小权限列表，如 `repo:read`、`doc:read`。 |
+| `constraints` | object<string,string> | 否 | 路径、分支、区域、超时等限制；不得含密钥字段。 |
+| `metadata` | object<string,string> | 否 | 资源展示/审计元数据；不得含密钥字段。 |
+| `status` | enum | 是 | `pending` / `active` / `disabled` / `revoked`。 |
+| `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 |
+| `audit` | object<string,string> | 否 | 审计上下文；不得含密钥字段。 |
+
+### 2.4 典型场景：Agent 辅助 NewAPI 重建/部署
+
+当 Manager 需要让 Agent 平台协助重建或部署 NewAPI 时，仍使用 `POST /api/agent/deployments`，但必须把任务表达为受控运维部署，不得把 VM、PostgreSQL、Redis、NewAPI key 等真实凭据写入请求体。
+
+请求体示例：
+
+```json
+{
+  "orchestration_plan": {
+    "intent_id": "intent_newapi_rebuild_20260503_001",
+    "template_hint": "newapi-rebuild-deploy",
+    "objective": "在批准窗口内重建 NewAPI 服务并回传健康检查、日志与资源使用摘要",
+    "risk_level": "high",
+    "budget": {
+      "max_tokens": 80000,
+      "max_cost_usd": 20,
+      "max_duration_sec": 3600
+    },
+    "constraints": {
+      "allowed_model_ids": ["gpt-5.4", "gpt-5.4-mini"],
+      "requires_approval": "true",
+      "rollback_required": "true",
+      "healthcheck_url_ref": "env://NEWAPI_HEALTHCHECK_URL"
+    },
+    "metadata": {
+      "tenant_id": "legacy-user-scope",
+      "project_id": "legacy-newapi-scope",
+      "correlation_id": "corr_newapi_20260503_001",
+      "service": "new-api",
+      "environment": "production",
+      "commit": "origin/main",
+      "runbook_ref": "heicode/docs/deploy/new-api-rebuild-deploy-runbook.md"
+    },
+    "agents": [
+      {
+        "role_template": "operator",
+        "goal": "按 runbook 执行构建、服务重启、健康检查和失败回滚；只通过 secret_ref/env 获取凭据",
+        "default_model_id": "gpt-5.4",
+        "runtime_execution": {
+          "profile_id": "aks-codex-ops",
+          "cloud_principal_refs": ["principal://users/user_123/agent-ops"],
+          "network_policy_ref": "netpol://bindings/newapi-prod/ops-egress"
+        },
+        "resource_grants": [
+          {
+            "grant_id": "grant_newapi_vm_ops",
+            "resource_id": "res_newapi_vm",
+            "resource_type": "cloud_resource",
+            "user_id": "user_123",
+            "binding_scope": "newapi-prod",
+            "tenant_id": "legacy-user-scope",
+            "project_id": "legacy-newapi-scope",
+            "target_role": "operator",
+            "target_agent_ref": "agent-operator-1",
+            "permission_scope": ["vm:ssh:approved-window", "service:restart", "log:read", "healthcheck:read"],
+            "constraints": {
+              "approval_id": "approval_newapi_001",
+              "window": "2026-05-03T10:00:00Z/2026-05-03T11:00:00Z",
+              "rollback_command_ref": "runbook://newapi/rollback"
+            },
+            "metadata": {
+              "host_ref": "env://NEWAPI_VM_HOST",
+              "service_name": "new-api"
+            },
+            "status": "active",
+            "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/user-123-newapi-prod-res-newapi-vm",
+            "audit": {
+              "created_by": "manager",
+              "approval_id": "approval_newapi_001"
+            }
+          },
+          {
+            "grant_id": "grant_newapi_runtime_env",
+            "resource_id": "res_newapi_runtime_env",
+            "resource_type": "cloud_resource",
+            "user_id": "user_123",
+            "binding_scope": "newapi-prod",
+            "tenant_id": "legacy-user-scope",
+            "project_id": "legacy-newapi-scope",
+            "target_role": "operator",
+            "target_agent_ref": "agent-operator-1",
+            "permission_scope": ["env:read:runtime", "secret:read:scoped"],
+            "constraints": {
+              "allowed_env_refs": "DATABASE_DSN,REDIS_URL,NEWAPI_SERVICE_TOKEN",
+              "plaintext_export_forbidden": "true"
+            },
+            "metadata": {
+              "secret_provider": "azure_key_vault",
+              "scope": "newapi-runtime"
+            },
+            "status": "active",
+            "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/user-123-newapi-prod-res-newapi-runtime-env",
+            "audit": {
+              "created_by": "manager",
+              "approval_id": "approval_newapi_001"
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Agent 平台返回的部署详情、日志、监控和审计中应至少能证明：构建版本/commit、服务重启结果、健康检查结果、资源使用情况、失败回滚状态。未执行真实 SSH/生产动作时，只能返回 `phase=planned` 或 `phase=pending_approval`。
+
+NewAPI 重建/部署的完成判定必须同时满足：
+
+1. `metadata.commit` 或部署详情中的 resolved commit 已在 VM 仓库中生效。
+2. 部署日志包含构建/compose/restart 的脱敏摘要。
+3. 健康检查返回成功，且监控接口能返回本次 deployment 的状态或资源摘要。
+4. 审计日志包含高风险审批 ID、执行者、目标环境和结果。
+5. 回滚指针或回滚命令引用已记录。
+
+### 2.5 成功响应
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "status": "accepted",
+    "agent_instances": [
+      {
+        "instance_id": "agi_abc123",
+        "role": "builder",
+        "phase": "pending"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 3. 部署状态与控制接口
+
+### 3.1 查询部署列表
+
+```http
+GET /api/agent/deployments?user_id=user_123&binding_scope=repo_default
+```
+
+返回：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "deployment_id": "dep_abc123",
+        "status": "accepted",
+        "phase": "pending",
+        "created_at": "2026-05-02T00:00:00Z",
+        "updated_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+### 3.2 查询单个部署
+
+```http
+GET /api/agent/deployments/{deployment_id}
+```
+
+返回应包含部署状态、phase、agent_instances、最近错误、资源授权摘要和预算消耗摘要。Agent 平台返回时必须对 `secret_ref` 以外的凭据信息做脱敏；原则上不返回任何明文凭据。
+
+### 3.3 停止部署
+
+```http
+POST /api/agent/deployments/{deployment_id}/stop
+```
+
+请求体可为空；如需原因可扩展：
+
+```json
+{
+  "reason": "user_requested",
+  "requested_by": "manager"
+}
+```
+
+成功：
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "status": "stopped"
+  }
+}
+```
+
+错误与幂等：
+
+| HTTP | business code | 说明 |
+|---:|---|---|
+| 200 | - | 已停止的部署重复停止也可返回 200，并保持 `status=stopped`。 |
+| 404 | `NOT_FOUND` | 部署不存在或不属于当前租户/项目。 |
+| 409 | `DEPLOYMENT_CONFLICT` | 部署已进入不可停止的终态，如 `completed` 且无运行实例。 |
+| 422 | `POLICY_REJECTED` | 高风险停止缺少审批记录或 reason 不合法。 |
+
+若停止请求触发异步回收，平台可返回 `status=stopping`；Manager 应继续通过事件、日志和监控接口确认最终状态。
+
+---
+
+## 4. 日志接口（Manager 拉取 Agent 平台）
+
+### 4.1 获取部署日志
+
+```http
+GET /api/agent/deployments/{deployment_id}/logs?agent_instance_id=agi_abc123&stream=stdout&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
+```
+
+Query：
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `agent_instance_id` | 否 | 不传则返回该 deployment 下全部实例日志。 |
+| `stream` | 否 | `stdout` / `stderr` / `system` / `audit`，默认全部。 |
+| `since` | 否 | RFC3339 时间，增量拉取起点。 |
+| `limit` | 否 | 默认 200，建议最大 1000。 |
+| `cursor` | 否 | 分页游标。 |
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "log_id": "log_001",
+        "deployment_id": "dep_abc123",
+        "agent_instance_id": "agi_abc123",
+        "stream": "stdout",
+        "level": "info",
+        "message": "task started",
+        "redacted": true,
+        "occurred_at": "2026-05-02T00:00:01Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+日志要求：
+
+- Agent 平台必须在返回前完成密钥脱敏。
+- `message` 不得包含密码、Token、私钥、连接串、云访问密钥。
+- Manager 只保存必要摘要和审计索引；长日志建议落对象存储并设置保留期。
+
+### 4.2 实时日志流（可选）
+
+```http
+GET /api/agent/deployments/{deployment_id}/logs/stream?agent_instance_id=agi_abc123
+Accept: text/event-stream
+```
+
+SSE event 示例：
+
+```text
+event: log
+data: {"log_id":"log_002","level":"info","message":"step completed","occurred_at":"2026-05-02T00:00:02Z"}
+```
+
+SSE 事件类型：
+
+| event | 说明 |
+|---|---|
+| `log` | 普通日志行，必须已脱敏。 |
+| `heartbeat` | 保活事件，建议 15-30 秒一次。 |
+| `error` | 流式读取错误；不包含敏感上下文。 |
+| `done` | 部署进入终态或服务端主动结束流。 |
+
+错误处理：
+
+| HTTP | business code | Manager 处理建议 |
+|---:|---|---|
+| 401/403 | `UNAUTHORIZED` / `FORBIDDEN_SCOPE` | 立即断开流并记录审计。 |
+| 404 | `NOT_FOUND` | 停止订阅并刷新部署详情。 |
+| 429 | `RATE_LIMITED` | 退避后重连，保留 `Last-Event-Id`。 |
+
+---
+
+## 5. 监控接口（Manager 拉取 Agent 平台）
+
+### 5.1 项目监控快照
+
+```http
+GET /api/agent/projects/{binding_scope}/dashboard-snapshot?window=1h
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "project_id": "project-a",
+    "active_instances": 3,
+    "phase_distribution": {
+      "pending": 1,
+      "running": 2,
+      "stopped": 0,
+      "failed": 0
+    },
+    "failure_rate_1h": 0.02,
+    "avg_task_duration": 185.3,
+    "budget": {
+      "tokens_used": 32000,
+      "cost_usd": 4.21,
+      "duration_sec": 930
+    },
+    "resource_usage": {
+      "cpu_millicores": 1200,
+      "memory_mb": 2048,
+      "network_rx_bytes": 102400,
+      "network_tx_bytes": 204800
+    },
+    "updated_at": "2026-05-02T00:05:00Z"
+  }
+}
+```
+
+### 5.2 单部署监控快照（建议平台实现）
+
+```http
+GET /api/agent/deployments/{deployment_id}/metrics?window=15m&step=60s
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "window": "15m",
+    "series": [
+      {
+        "metric": "tokens_used",
+        "unit": "count",
+        "points": [["2026-05-02T00:00:00Z", 1200]]
+      },
+      {
+        "metric": "cpu_millicores",
+        "unit": "millicore",
+        "points": [["2026-05-02T00:00:00Z", 500]]
+      }
+    ]
+  }
+}
+```
+
+建议指标：`tokens_used`、`cost_usd`、`duration_sec`、`cpu_millicores`、`memory_mb`、`restart_count`、`tool_call_count`、`error_count`、`queue_latency_ms`。
+
+---
+
+## 6. 事件与审计接口
+
+### 6.1 部署事件
+
+```http
+GET /api/agent/deployments/{deployment_id}/events?since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "event_id": "evt_001",
+        "event": "deployment.accepted",
+        "schema_version": 1,
+        "user_id": "user_123",
+        "channel_id": "channel_abc",
+        "binding_scope": "repo_default",
+        "deployment_id": "dep_abc123",
+        "correlation_id": "corr_20260502_001",
+        "occurred_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+常用事件名：
+
+| event | 说明 |
+|---|---|
+| `deployment.accepted` | 平台接受部署请求。 |
+| `instance.phase_changed` | 子 Agent phase 变化。 |
+| `sk_snapshot_refreshed` | SK 快照解析/刷新完成。 |
+| `resource_grant.attached` | 资源授权已绑定到实例。 |
+| `resource_grant.revoked` | 授权被撤销或禁用。 |
+| `budget.threshold_reached` | 预算阈值触发。 |
+| `deployment.failed` | 部署失败。 |
+
+### 6.2 审计日志
+
+```http
+GET /api/agent/audit-logs?user_id=user_123&binding_scope=repo_default&actor=agent_control_plane&action=deployment.accepted&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "audit_id": "aud_001",
+        "actor": "agent_control_plane",
+        "action": "deployment.accepted",
+        "resource": "dep_abc123",
+        "user_id": "user_123",
+        "channel_id": "channel_abc",
+        "binding_scope": "repo_default",
+        "request_id": "req_001",
+        "correlation_id": "corr_20260502_001",
+        "result": "ok",
+        "occurred_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+---
+
+## 7. SK 快照接口
+
+### 7.1 触发解析/刷新
+
+```http
+POST /api/agent/sk-snapshots/resolve
+```
+
+请求：
+
+```json
+{
+  "deployment_id": "dep_abc123"
+}
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "deployment_id": "dep_abc123",
+    "items": [
+      {
+        "snapshot_id": "sks_001",
+        "deployment_id": "dep_abc123",
+        "user_id": "user_123",
+        "binding_scope": "repo_default",
+        "source_type": "git",
+        "source_ref": "main:skills/heicode/**@sha_xxx",
+        "resolved_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+### 7.2 查询部署 SK 快照
+
+```http
+GET /api/agent/deployments/{deployment_id}/sk-snapshots
+```
+
+Query：
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `user_id` | 建议 | 与 `X-User-Id` 或 deployment 的 `user_context.user_id` 一致。 |
+| `binding_scope` | 建议 | 与 `X-Binding-Scope` 或 deployment 的资源授权作用域一致。 |
+| `source_type` | 否 | `git` / `upload`，用于筛选。 |
+| `limit` | 否 | 默认 100，最大 500。 |
+| `cursor` | 否 | 分页游标。 |
+
+成功响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "snapshot_id": "sks_001",
+        "deployment_id": "dep_abc123",
+        "user_id": "user_123",
+        "binding_scope": "repo_default",
+        "source_type": "git",
+        "source_ref": "main:skills/heicode/**@sha_xxx",
+        "artifact_ref": "artifact://bindings/repo_default/sk/sks_001",
+        "checksum": "sha256:example-redacted",
+        "status": "ready",
+        "resolved_at": "2026-05-02T00:00:00Z"
+      }
+    ],
+    "next_cursor": "cur_002",
+    "total": 1
+  }
+}
+```
+
+错误处理：
+
+| HTTP | business code | 说明 |
+|---:|---|---|
+| 404 | `NOT_FOUND` | deployment 不存在或不属于当前租户/项目。 |
+| 410 | `CURSOR_EXPIRED` | cursor 过期，使用不带 cursor 的查询重拉。 |
+| 422 | `SK_SOURCE_UNRESOLVABLE` | 快照来源不可解析，详情在事件/日志中查看。 |
+
+---
+
+## 8. 安全校验清单
+
+Manager 发给 Agent 平台前必须执行：
+
+1. `user_id`、`binding_scope`、`target_role` 与部署计划一致。
+2. 凭据型资源只传 `secret_ref`，不传明文凭据。
+3. `metadata`、`constraints`、`audit` 的 key 中不得出现 `password`、`token`、`secret`、`private_key`、`access_key`、`credential` 等敏感词。
+4. `repo_url` 不得包含用户名、密码或访问 Token。
+5. `permission_scope` 使用最小权限；生产写操作必须携带客户端审批记录，Agent 平台不得自行补批。
+6. 高风险操作（生产部署、云资源修改、删除、扩容）必须设置 `risk_level=high`，Agent 平台执行前只校验客户端审批证据。
+7. 所有日志/事件/审计返回给 Manager 前必须脱敏。
+
+Agent 平台不承担高危操作审批主体。审批只发生在客户端；Agent 平台只能在执行前校验以下字段和策略是否一致：
+
+| 校验项 | 要求 |
+|---|---|
+| `approval_id` | 必须存在于高危任务的 `constraints` 或 `audit`，并可追溯到客户端审批记录。 |
+| 审批主体 | 审批用户必须与 `user_context.user_id`、`resource_grants[].user_id` 或授权代理主体一致。 |
+| 审批范围 | 审批范围必须覆盖 `binding_scope`、`permission_scope`、目标环境、资源 ID 和操作类型。 |
+| TTL / 时间窗口 | 审批记录必须未过期；若使用 `window` 或 TTL，当前执行时间必须落在允许范围内。 |
+| `risk_level` | 高危资源写入、生产部署、云资源修改、删除和扩容必须为 `high`。 |
+| 策略 | 平台 policy、Key Vault 访问策略、Kubernetes/Workload Identity、网络策略和最小权限约束均必须允许本次动作。 |
+
+任一校验不通过时，Agent 平台应返回 `POLICY_REJECTED` 或 `FORBIDDEN_SCOPE`，不得发起额外批准流程。
+
+### 8.1 字段级约束速查
+
+| 对象/接口 | 必填最小集合 | 禁止内容 |
+|---|---|---|
+| `orchestration_plan` | `intent_id`、`template_hint`、`objective`、`risk_level`、`budget`、`user_context`、`billing_context`、`agent_runtime`、`metadata.correlation_id`、`agents[]` | 密钥、连接串、真实主机登录密码、NewAPI key 原文。 |
+| `agents[]` | `role_template`、`goal` | 让子 Agent 绕过 Manager/Agent 审计的指令。 |
+| `runtime_execution` | 任一字段存在时 `profile_id` 必填 | 明文 kubeconfig、SSH key、云访问密钥。 |
+| `resource_grants[]` | `grant_id`、`resource_id`、`resource_type`、`user_id`、`binding_scope`、`target_role`、`target_agent_ref`、`permission_scope`、`status` | 明文 `password`、`token`、`private_key`、`access_key`、`credential`、数据库 DSN。 |
+| 日志/事件/审计返回 | `request_id` 或 `correlation_id`，以及发生时间 | 未脱敏命令行、环境变量 dump、密钥片段。 |
+| NewAPI 重建/部署场景 | `approval_id`、`rollback_command_ref`、健康检查引用、运行环境 `secret_ref` | 真实 VM 密码、PostgreSQL/Redis 连接串、NewAPI 服务令牌。 |
+
+### 8.2 联调验收清单
+
+- 创建部署请求只包含 `secret_ref`/`env://`/`runbook://` 引用，不包含真实凭据。
+- `user_id` 与 `binding_scope` 在 user context、resource grant、事件和审计中一致。
+- `risk_level=high` 的生产运维任务包含 `approval_id` 和回滚引用。
+- 日志、事件、监控、审计接口都能通过 `correlation_id` 串联。
+- NewAPI 重建/部署只在实际执行并通过健康检查后标记为已部署；未执行时状态只能是 `planned`、`pending_approval`、`accepted` 或 `running`。
+- Manager 本地 `/api/agent/*` 占位端点通过 payload 校验不等于生产 Agent 平台已上线。
+
+---
+
+## 9. Manager 侧当前实现映射
+
+当前代码中可用于对齐/验证 payload 的 Manager 侧端点：
+
+| Manager 路由 | 用途 |
+|---|---|
+| `POST /api/agent/deployments` | 校验并接受 orchestration_plan。 |
+| `GET /api/agent/deployments` | 按 user/binding scope 查询部署。 |
+| `GET /api/agent/deployments/:deployment_id` | 查询部署详情。 |
+| `POST /api/agent/deployments/:deployment_id/stop` | 停止部署。 |
+| `GET /api/agent/deployments/:deployment_id/logs` | 查询脱敏日志占位/联调日志。 |
+| `GET /api/agent/deployments/:deployment_id/metrics` | 查询单部署指标占位/联调指标。 |
+| `GET /api/agent/deployments/:deployment_id/events` | 查询事件。 |
+| `POST /api/agent/sk-snapshots/resolve` | 解析 SK 快照。 |
+| `GET /api/agent/deployments/:deployment_id/sk-snapshots` | 查询 SK 快照。 |
+| `GET /api/agent/projects/:project_id/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容。 |
+| `GET /api/agent/audit-logs` | 审计日志。 |
+
+生产对接时，Manager 应把相同契约的请求发送给 Agent 平台；本地 Manager 端点仅作为最小验证与控制面占位，不代表所有日志/监控平台能力已完整实现。
+
+当前本地 `logs` 与 `metrics` 端点只返回脱敏占位/联调数据，用于验证 Manager ↔ Agent payload、路由和验收流程。生产级实时日志流 `GET /api/agent/deployments/{deployment_id}/logs/stream` 仍属于 Agent 平台能力；Manager 不得把“本地占位通过”误报为“生产日志/监控已上线”。