myxce/docs/Scheduler-Agent-设计文档.md

Unified Scheduler Agent Framework — 设计文档

项目代号：scheduler-agent 文档版本：v1.3 最近更新：2026-08-13 文档状态：实施中（Phase 0-2 代码完成并集群验证 ✅；Phase 3-4 后端适配器未开始。Phase 0-1 E2E 2026-08-12 通过；Phase 2 SSE 事件流 + 4 高级工具 2026-08-12 实施并验证；人类可读 jobid 2026-08-13 落地）

---

1. 文档目的

本文档定义"自然语言调度器管理 Agent 框架"的完整设计——一套架构同时适配自研调度器、LSF、Slurm、Kubernetes，让用户通过自然语言完成集群管理操作。

本文档是设计权威来源（source of truth），实施进度、架构变更、决策记录均在此维护。

---

2. 背景与项目定位

2.1 为什么做

HPC 集群（调度器）的使用者——研究员、运维——操作门槛高。bjobs/squeue/bsub 等命令行语法复杂，跨系统（LSF/Slurm/K8s）命令不互通。AI Agent 可以将这些操作抽象为自然语言。

2.2 核心定位

我们是调度器开发者，不是壳。

与 iris-mcp、srunx 等项目的结构性差异：

对比维度	其他项目	本项目
交互方式	CLI 文本解析	内核级嵌入 Agent 原生接口
事件能力	无，只能轮询	实时事件流（自研独有）
授权粒度	粗粒度	细粒度 RBAC
API 能力	受限	高级 API 原生支持

2.3 目标用户

• 研究员：提交作业、查状态、诊断失败原因，用自然语言
• 运维：集群监控、资源管理、问题排查，用自然语言

2.4 市场叙事

• Phase 0-2：自研调度器体验碾压 LSF/Slurm（实时 + 自然语言）
• Phase 3-4："Any cluster, natural language"

---

3. 总体架构

3.1 分层架构图

┌─────────────────────────────────────────────────────────────────┐
│ Layer 0 · 用户界面层                                             │
│   🧑 用户 ──→ 💻 CLI (Claude Code)                               │
│              → 🌐 Web Chat (自建 Chat UI)                        │
│              → 🔌 IDE Plugin (Cursor / VS Code)                  │
└─────────────────────────────────────────────────────────────────┘
                              │ 自然语言
┌─────────────────────────────────────────────────────────────────┐
│ Layer 1 · 推理规划层                                             │
│   🧠 Orchestrator LLM                                           │
│      意图识别 → 规划 → 工具调用 → 纠错                          │
│      (Claude / GPT / 本地模型)                                   │
└─────────────────────────────────────────────────────────────────┘
                              │ Tool Call (JSON-RPC)
┌─────────────────────────────────────────────────────────────────┐
│ Layer 2 · Agent 核心层                                           │
│   🔌 MCP 协议 (stdio/SSH/HTTP)                                   │
│   ⚙️ 核心引擎 (Tool 路由 · Session · 多后端调度)                │
│   📦 统一资源模型 URM (Job/Queue/Node)                           │
│   🔐 鉴权 + 审计 (RBAC · 审计日志)                              │
│   📋 Session 上下文管理                                          │
└─────────────────────────────────────────────────────────────────┘
                              │ Adapter 接口
┌─────────────────────────────────────────────────────────────────┐
│ Layer 3 · 后端适配器层                                           │
│   🏆 Native Adapter (自研调度器) ★ 实时事件流                   │
│   📟 LSF Adapter (CLI/Python SDK)                               │
│   📡 Slurm Adapter (REST API/CLI)                                │
│   ☸️ K8s Adapter (client-go/Watch)                               │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│ Layer 4 · 调度器层                                               │
│   🚀 自研调度器 (事件总线 · RBAC · 高级 API)                    │
│   📡 LSF 集群 (9.x/10.x) · 📡 Slurm 集群 (23.x+)                │
│   ☸️ Kubernetes (1.28+)                                         │
└─────────────────────────────────────────────────────────────────┘

3.2 数据流

用户自然语言 → LLM → MCP Tool Call → Agent 核心 → Adapter → 调度器
                                                          ↑
                                       事件流实时回传（自研独有）

---

4. 核心设计

4.1 统一资源模型（URM）

每个调度器的概念不同。URM 提供通用抽象，同时通过 extensions 暴露后端专有能力。

4.1.1 核心类型

type URMJob struct {
    ID              string            `json:"id"`
    Name            string            `json:"name"`
    Status          JobStatus         `json:"status"`   // pending | running | succeeded | failed | cancelled | suspended | unknown
    RawStatus       string            `json:"raw_status"` // 原始状态（PEND / RUNNING / Suspended）
    Queue           string            `json:"queue"`      // 队列 / partition / namespace
    Nodes           int               `json:"nodes"`
    Cores           int               `json:"cores"`
    GPUs            int               `json:"gpus"`
    MemoryBytes     int64             `json:"memory_bytes"`
    WalltimeSeconds int               `json:"walltime_seconds"`
    Dependencies    []JobRef          `json:"dependencies"`
    SubmissionTime  time.Time         `json:"submission_time"`
    StartTime       *time.Time        `json:"start_time,omitempty"`
    ExitCode        *int              `json:"exit_code,omitempty"`
    Owner           string            `json:"owner"`
    LogsURL         string            `json:"logs_url,omitempty"`
    Extensions      map[string]any    `json:"extensions,omitempty"` // 后端专有能力
}

type URMQueue struct {
    Name                 string        `json:"name"`
    Status               string        `json:"status"` // active | inactive | draining
    NodeCount            int           `json:"node_count"`
    RunningJobs          int           `json:"running_jobs"`
    PendingJobs          int           `json:"pending_jobs"`
    MaxWalltimeSeconds   int           `json:"max_walltime_seconds"`
    DefaultResources     *ResourceSpec `json:"default_resources,omitempty"`
    Extensions           map[string]any `json:"extensions,omitempty"`
}

type URMNode struct {
    Name              string   `json:"name"`
    Status            string   `json:"status"` // idle | busy | down | drain | unknown
    CoresTotal        int      `json:"cores_total"`
    CoresUsed         int      `json:"cores_used"`
    MemoryBytesTotal  int64    `json:"memory_bytes_total"`
    MemoryBytesUsed   int64    `json:"memory_bytes_used"`
    GPUCount          int      `json:"gpu_count"`
    Features          []string `json:"features"`
    Extensions        map[string]any `json:"extensions,omitempty"`
}

4.1.2 设计原则

• 核心字段 = 所有调度器都有，LLM 使用同一套 prompt 理解
• 扩展字段 = Extensions map 兜底后端专有能力（fairshare / GRES / tolerations）
• 能力文档动态注入 = LLM prompt 中动态注入当前后端的能力文档

4.2 后端适配器层

4.2.1 SchedulerAdapter 接口

type SchedulerAdapter interface {
    // ── 读操作 ──
    ListJobs(ctx context.Context, filter JobFilter) ([]*URMJob, error)
    GetJob(ctx context.Context, id string) (*URMJob, error)
    ListQueues(ctx context.Context) ([]*URMQueue, error)
    ListNodes(ctx context.Context) ([]*URMNode, error)
    GetMetrics(ctx context.Context) (*Metrics, error)
    GetJobLogs(ctx context.Context, id string, opts LogOpts) ([]string, error)

    // ── 写操作 ──
    SubmitJob(ctx context.Context, spec *JobSpec) (*URMJob, error)
    CancelJob(ctx context.Context, id string) (*CancelResult, error)
    HoldJob(ctx context.Context, id string) error
    ReleaseJob(ctx context.Context, id string) error
    ModifyJob(ctx context.Context, id string, changes *JobModification) (*URMJob, error)

    // ── 高级（可选实现） ──
    CreateReservation(ctx context.Context, spec *ReservationSpec) (*Reservation, error)
    AnalyzeFailure(ctx context.Context, jobID string) (*FailureAnalysis, error)

    // ── 事件流 ──
    WatchJobs(ctx context.Context, filter EventFilter) (<-chan JobEvent, error)
}

4.2.2 各后端实现策略

后端	适配器语言	实现方式	事件流
自研调度器	Go	调用 apiserver REST API（cgo 桥接 C backend）	✅ 原生实时事件推送
LSF	Go + Python sidecar	Phase 0-1: bjobs/bsub CLI 解析；Phase 2+: Python SDK	⚠️ 轮询
Slurm	Go	Phase 0-1: squeue/sbatch CLI 解析；Phase 2+: slurmrestd	⚠️ 轮询
Kubernetes	Go	client-go 直接调用 K8s API Server	✅ Informer/Watch

⚠️ 已修正（2026-07-26）：myxce 调度内核是 C（Cap'n Proto + Raft HA），Go 只存在于 apiserver（cgo 桥接 libxce）和 xcecli。因此 Native Adapter 的实现路径是 mcp-server 调用 apiserver 现成 REST API，而非进程内 import Go package。

4.3 语言选择策略

主体语言：Go。

1. 自研调度器是 Go 栈——Adapter 可 import 内部 client 包（性能最优）
2. 单二进制分发——ssh 到 login node 不需要装运行时
3. os/exec + stdout 解析天然适配 CLI-based adapter（LSF/Slurm）
4. 并发/事件流——goroutine + channel 完美适配 WatchJobs

分阶段语言演进：

Phase 0-1:  纯 Go (MCP Server + 所有 adapter)
                ↓ 当需要 LSF C 库 / Python SDK 深度集成时
Phase 2+:   Go 主体 + LSF 侧 Python Sidecar（UDS/gRPC 通信）

4.4 MCP 协议接口（对外暴露的工具集）

通过 MCP Server 暴露给 Claude Code、Cursor 等 MCP 客户端，或自建的 Chat UI。

4.4.1 读工具

Tool	说明
scheduler_list_jobs(filter)	列出作业，支持按状态/队列/owner 过滤
scheduler_get_job(id)	获取作业详情
scheduler_list_queues()	列出队列及容量、运行/排队数
scheduler_list_nodes()	列出节点及资源使用情况
scheduler_job_logs(id, tail?, since?)	获取作业输出日志
scheduler_cluster_metrics()	集群整体负载、使用率概览

4.4.2 写工具（默认 require confirm）

Phase 1 已实现（2026-08-01）：

Tool	说明	confirm 机制
scheduler_submit(template, command, ...)	提交作业，支持模板（general_serial 通用串行脚本）+ 格式化参数；dry_run=true 返回 review card	dry_run review 模式 + destructive 注解
scheduler_cancel(id)	取消作业（→ action kill，默认 SIGTERM）	destructive 注解，客户端确认
scheduler_hold(id)	暂停止作业（→ action stop，默认 SIGTSTP）	destructive 注解，客户端确认
scheduler_release(id)	恢复暂停的作业（→ action resume，默认 SIGCONT）	destructive 注解，客户端确认

Phase 1 未做：scheduler_modify(id, changes) —— apiserver 当前无 modify 端点（job control 仅支持 kill/stop/resume/checkpoint），需新增后端端点，推迟。

confirm 实现说明：MCP 协议（mcp-go v0.57.0）无原生 requiresConfirmation 字段，只有 ToolAnnotation{ReadOnlyHint, DestructiveHint}。实现采用两层：① scheduler_submit 用 dry_run 参数作为协议内 review 门（先返回 resolved JobSpec 供用户确认，再以 dry_run=false 真正提交）；② cancel/hold/release 标记 DestructiveHint: true，由 MCP 客户端（Claude Code）在执行前弹出确认。这与设计 §4.5"写操作默认 require confirm"一致。

4.4.3 高级工具

Tool	说明
scheduler_analyze_failure(id)	自动诊断作业失败原因（日志分析 + 退出码 + 资源分析）
scheduler_suggest_resources(description)	根据自然语言任务描述推荐资源配置
scheduler_estimate_wait_time(queue_spec)	估算排队时间

4.5 安全模型

这是作为调度器厂商最重要的护城河。Agent 的错误操作会直接侵蚀对产品的信任。

4.5.1 安全链路

┌──────┐    ┌──────┐    ┌───────────┐    ┌────────────┐    ┌─────────┐
│ 用户  │ →  │ LLM  │ →  │ Agent 层  │ →  │ Audit Proxy│ →  │ 调度器  │
└──────┘    └──────┘    └───────────┘    └────────────┘    └─────────┘
                               ↑               │
                               │               └→ 审计日志
                               └── 写操作 require confirm
                                   Autopilot 需用户显式启用

4.5.2 安全原则

1. 所有写操作默认 require confirm：LLM 生成命令/参数，展示给用户确认后再执行
2. Autopilot 模式：用户通过 --autopilot 显式启用后，Agent 可在授权范围内自主执行
3. 完整审计日志：每条 AI 操作记录 [timestamp] [user] [action] [params] [confirmed?]
4. 拒绝不安全操作：直接修改调度器配置、操作他人作业（无授权时）、sudo/root 操作
5. 操作范围绑定：用户可通过 prompt 限定 Agent 作用域（"只操作我的作业" / "只在这个队列"）

4.5.3 凭证模型

• mcp-server 用服务账号 API Key（xce_ak_ 前缀）调用 apiserver，而非透传终端用户 JWT
• API Key 不做 IP 绑定（面向长期运行的自动化客户端，源 IP 不稳定）
• Phase 0 用 mcp_readonly 角色（仅 :view 权限）—— ✅ 已实施（2026-07-26）
• Phase 1 引入 mcp_operator 角色 —— ✅ 已实施（2026-08-01）：5 个 *:view（domain all）+ queue:submit + job:control（domain all）。覆盖 scheduler_submit 和 cancel/hold/release 的全部写端点权限。不含 host:control / cluster:control / rbac:* / file:* / user:*——MCP 服务账号仍不能管理集群配置或其他用户/角色。
• 生成方式：管理员用 POST /xce/v1/apikeys（rbac:control，仅 cluster_admin）创建，role_name: "mcp_operator"。handler 同时注册 key 和 AddRoleForUser(username, role)。

4.6 事件流设计

4.6.1 当前调研结论（2026-07-30）

XCE 产品目前零对外实时推送实现。 所有客户端通信均为 100% 请求/响应模式。

已有（进程内）：

• C Controller → NotificationHandler（OnJobCreated/OnJobUpdated/OnJobFinished...）→ DefaultHandler → 写入内存 DataStore
• 事件到进程就停了，没有对外通道

确认没有的：

• SSE endpoint、WebSocket、gRPC streaming、长轮询、Subscribe/Watch API、Pub/Sub 均不存在
• Gin 已带 github.com/gin-contrib/sse（间接依赖），无需额外引入

4.6.2 设计方向

在 apiserver 侧加 SSE endpoint + EventBroker，把 DefaultHandler 收到的事件同时广播给订阅者。

C Controller ──OPCode_push──→ apiserver ──SSE──→ mcp-server / 浏览器
                               NotificationHandler
                               ↓ 仅需在 handler 加一行
                                  broker.Publish(event)

4.6.3 工作量估算

任务	工作量	位置
apiserver 加 SSE endpoint + EventBroker	1 天	controllers/events.go（新建）
NotificationHandler → Broker 转发	0.5 天	handler.go 加 publish
RBAC event:view 权限	0.5 天	config/rbac.yaml + middleware
schedulerclient 加 WatchJobs()	0.5 天	httpclient.go SSE 解析
mcp-server 集成	0.5 天	Agent 工作流：提交→监控→自动处理

总计 2-3 天。 决策：Phase 1 走通写操作后再接入。

---

5. 实施路线图

5.1 Phase 0 — 只读 MCP Server（✅ 已完成代码，待集群验证）

• 实现自研调度器的只读 adapter（ListJobs / GetJob / ListQueues / ListNodes / GetJobLogs）
• 暴露 6 个 MCP 读工具
• 验证：自然语言问"我的作业状态"、"队列里有什么"

输入：schedulerclient Go package（只读接口） 输出：可运行的 MCP Server，连接 Claude Code 后可以用自然语言查集群状态

5.2 Phase 1 — 作业提交 + 模板（✅ 已完成代码，待集群验证；2026-08-01）

• Submit / Cancel / Hold / Release 写操作工具（✅ 4 个已实现；Modify 因 apiserver 无端点推迟）
• 作业模板（✅ general_serial 通用串行脚本已实现；registry 机制支持后续扩展 GPU/array/dependency）
• 严格的参数校验 + review 模式（✅ scheduler_submit 的 dry_run=true 返回 resolved JobSpec 供用户确认）
• 安全性审查（✅ destructive 注解 + mcp_operator RBAC 角色）
• 待集群验证：运行中的 apiserver + 生成 mcp_operator API Key + Claude Code MCP 配置（同 Phase 0 阻塞项）

5.3 Phase 2 — 监控 + 纠错 loop（✅ 已实施 2026-08-12）

• Agent 工作流：提交 → WatchJobs 接收事件 → 发现失败 → 分析日志 → 建议修复
• 自研调度器的实时事件流是核心差异点：作业状态变化时 adapter 直接推送事件，LLM 自动触发处理
• 与 LSF/Slurm 适配器的"轮询"模式形成体验代差
• 已实施：apiserver /xce/v1/events SSE + EventBroker（ADR-004）；schedulerclient WatchJobs()；mcp-server 4 个高级工具（scheduler_wait_job/scheduler_analyze_failure/scheduler_suggest_resources/scheduler_estimate_wait_time）。t1 集群验证：SSE 流推送 PEND→RUN→DONE 事件、WatchJobs 捕获完整生命周期、4 工具全部工作。顺带修复：schedulerclient ListJobs 的 filter 参数（queue_name → filter=queue_name:eq:...，原参数被 apiserver 400 拒绝）。

5.4 Phase 3 — LSF 适配器（+1 月）

• LSF adapter：先用 CLI 解析（bjobs -o "id stat queue slots" -noheader），需要时加 Python Sidecar
• 目标：LSF 用户迁移到自研调度器时体验零摩擦

5.5 Phase 4 — Slurm + K8s 适配器（+1 月）

• Slurm adapter：slurmrestd REST API + CLI 回退
• K8s adapter：client-go
• 市场叙事："Any cluster, natural language"

---

6. 代码仓库结构

6.1 目标结构（scheduler-agent 全量）

scheduler-agent/
├── cmd/
│   └── mcp-server/            # MCP Server 入口
├── internal/
│   ├── server/                # MCP Server 核心
│   │   ├── server.go          # JSON-RPC 处理
│   │   ├── tools.go           # Tool 定义注册
│   │   └── session.go         # Agent session 状态管理
│   ├── urm/                   # 统一资源模型
│   │   ├── job.go
│   │   ├── queue.go
│   │   └── node.go
│   └── adapters/              # 后端适配器
│       ├── native/            # 自研调度器
│       │   └── adapter.go
│       ├── lsf/               # LSF
│       │   ├── adapter.go
│       │   └── parser.go      # CLI 输出解析
│       ├── slurm/             # Slurm
│       │   ├── adapter.go
│       │   └── parser.go
│       └── k8s/               # Kubernetes
│           └── adapter.go
├── test/
│   └── golden/                # Golden test

6.2 当前落地位置（myxce 仓库内）

myxce/src/frontend/
├── apiserver/                 # Go REST API server（cgo 桥接 C backend）
│   └── config/rbac.yaml       #   含 mcp_readonly（Phase 0）+ mcp_operator（Phase 1）角色
├── xcecli/                    # Go CLI 工具
├── schedulerclient/           # ← Phase 0-1 ✅ scheduler-agent Go client（读 + 写）
│   ├── client.go              #   Client interface（6 只读 + 4 写方法）
│   ├── types.go               #   URMJob / URMQueue / URMNode
│   ├── statusmap.go           #   状态映射（含单测）
│   ├── httpclient.go          #   resty HTTP 实现（GET）
│   └── write.go               # ← Phase 1 写接口：JobSpec / SubmitJobResult / doPost /
│                              #   SubmitJob / CancelJob / HoldJob / ReleaseJob（含单测）
└── mcp-server/                # ← Phase 0-1 ✅ MCP Server 二进制
    ├── cmd/main.go            #   入口，注册 10 个 MCP Tool（6 只读 + 4 写），stdio server
    └── internal/
        ├── app.go             #   Tool handlers 连接 schedulerclient（读 + 写）
        └── templates.go       # ← Phase 1 作业模板 registry + general_serial（含单测）

---

7. 测试策略

测试是商业化的真正护城河。模型不重要，验证套件才重要。

7.1 测试分层

test/
├── backends/
│   ├── native/      # 自研调度器 mock
│   ├── lsf/         # 需要 LSF 测试集群
│   ├── slurm/       # 需要 Slurm 测试集群
│   └── k8s/         # kind/minikube
├── scenarios/
│   ├── simple_submit.yaml        # "帮我跑这个脚本"
│   ├── job_dependency.yaml       # "按 A→B→C 顺序提交"
│   ├── job_array.yaml            # "做 100 个参数的扫描"
│   ├── failure_diagnosis.yaml    # "为什么失败了"
│   ├── multi_step_pipeline.yaml  # "提交→监控→分析→重试"
│   └── cross_platform.yaml       # 同场景在不同后端的表现对比
├── golden/
│   └── expected_tool_calls/      # 每个 scenario 期望的 tool call 链
└── integration/
    └── agent_e2e_test.go         # 端到端：自然语言输入 → 验收结果

7.2 Golden Test 回归

每次 adapter 改动用 golden test 回归——同样的自然语言输入，产生同样的 tool call 序列。

---

8. 设计原则

8.1 Narrow First（先窄后宽）

先吃透自研调度器，再扩展。自研调度器适配器的体验必须显著优于第三方适配器，形成竞争壁垒。

8.2 功能 vs 兼容的取舍

URM 不做最小公分母。核心字段通用，扩展字段用 extensions 兜底。LLM prompt 动态注入后端能力文档。

• 通用能力：所有后端一致
• 专有能力：extensions 暴露，模型自动识别是否可用

8.3 Write-Protected by Default

所有写操作默认 require confirm。Audit Log 是产品的一等公民，不是后加的功能。

8.4 LLM 是路由器，不是执行器

LLM 负责意图识别、规划、纠错。调度器交互由 adapter 的确定性代码执行。

• 调度器升级只需更新 adapter，不需调优模型
• 错误路径清晰：LLM 幻觉不会传递到调度器操作层

8.5 渐进的上下文窗口管理

Agent loop 跨多轮调度器轮次保持上下文：

• 作业 <= 60s：一步到位（提交→等待→返回）
• 作业 > 60s：事件流异步通知，状态持久化，Agent 通过 GetJob() 恢复
• 上下文满：auto-compact 历史轮次，保留最新状态摘要

---

9. 决策记录（ADR）

9.1 ADR-001：mcp-server 用服务账号 API Key 鉴权（已确认）

• 状态：✅ 已实施（2026-07-26）
• 决策：mcp-server 用服务账号 API Key（xce_ak_ 前缀）调用 apiserver，而非透传终端用户 JWT
• 理由：API Key 面向长期运行的自动化客户端，源 IP 不一定稳定，不做 IP 绑定
• 实现：store/apikey.go + models/apikey.go + controllers/auth.go + middleware/validatehandler.go + router/routers.go + config/rbac.yaml

9.2 ADR-002：schedulerclient 放在 myxce 仓库内（已确认）

• 状态：✅ 已实施
• 决策：代码放在 myxce/ 仓库内新增目录（与 apiserver/xcecli 同级），不另起独立仓库

9.3 ADR-003：Native Adapter 走 apiserver REST API（已确认）

• 状态：✅ 已确认（2026-07-26）
• 决策：mcp-server 调用 apiserver 现成 REST API，不是进程内 import Go package
• 理由：myxce 调度内核是 C，Go 只存在于 apiserver（cgo 桥接）和 xcecli。直接 cgo 链接 libxce 绕开 apiserver 复杂度接近重写一次 apiserver

9.4 ADR-004：事件流对外通道用 SSE（✅ 已实施 2026-08-12）

• 状态：✅ 已实施（2026-08-12）。/xce/v1/events SSE + EventBroker + WatchJobs() + mcp-server 4 高级工具，t1 集群验证通过。
• 决策：apiserver 加 SSE endpoint + EventBroker，复用已有 NotificationHandler 进程内事件

---

10. 当前进度状态（2026-08-01）

10.1 已完成

Phase 0（只读链路）：

任务	内容	状态
Task #1	架构与设计文档	✅
Task #2	API Key 鉴权机制（TDD）	✅ 全绿
Task #3	schedulerclient 只读客户端	✅ 33 单测
Task #4	mcp-server MCP 二进制	✅ 构建通过

Phase 1（写操作链路，2026-08-01）：

任务	内容	状态
Task #5	schedulerclient 写接口（Submit/Cancel/Hold/Release + JobSpec + doPost）	✅ 12 单测
Task #6	mcp-server 4 个写工具 + general_serial 模板 + dry_run review 模式	✅ 14 单测
Task #7	修复 6 个只读工具注解（原被默认误标 destructive）	✅
Task #8	mcp_operator RBAC 角色（queue:submit + job:control）	✅ 测试全绿

Phase 0-1 完整链路（代码层面就绪）：

用户自然语言 → Claude Code → MCP stdio → mcp-server → schedulerclient → apiserver REST API → 调度器
                                  （读：6 只读工具 + 写：4 写工具）

10.2 待办（阻塞项）

#	阻塞项	状态	责任方
1	运行中的 apiserver + C 编译环境	✅ t1 单节点 controller + apiserver + scheduler + worker 已启动（2026-08-01）	已完成
2	生成 API Key	✅ mcp_operator key 已生成并验证读 + submit	已完成
3	配置 Claude Code MCP	🚫 拿到集群 API 后配置	用户
4	Phase 1 端到端验证：提交→列表→hold→release→cancel	✅ 完成（2026-08-12）：mcp_operator API key → mcp-server（scheduler_submit/get_job）→ apiserver REST → controller → scheduler → worker，作业 submit→运行→DONE；cancel（kill）→ EXIT；hold/release（stop/resume）链路可用。完整 Agent 链路验证通过。	已完成

10.2b 本次集群验证发现并修复的 apiserver bug（2026-08-01）

Bug	现象	修复
whitelist 缺 /xce/v1/apikeys	API Key 生成端点 403 "URL is not allowed"	middleware/whitelist.go 加 /xce/v1/apikeys（bug-1489，已修）
control 的 job_status int64 断言	control 返回 "Invalid job_status"	controllers/jobs.go 加 normalizeJobStatus() 兼容 int/int64/float64（已修）
control 链路 500（未修）	hold/release/cancel 返回 500，请求未达 controller	待排查（bug-1490）
读接口 OrderMap 解析（已修）	scheduler_list_nodes/queues/jobs 实体数量对但字段全空	httpclient.go 用 apiRow 解析列式格式（bug-1491，已修 + 真实验证）
作业全部 PEND（已修）	提交的作业从不被调度（scheduler 日志 0 job 行；新作业也 PEND）	已修复（2026-08-11）：bug-1494 两个根因——dispatch-fail 不重试（bug-1510）+ worker rejoin 后 slots 不更新（bug-1511），见 docs/left_scheduler_work.md §一

10.3 未决决策项

• 事件流接口（SubscribeJobEvents）对外通道设计 —— 已验证前提成立，待 Phase 2 实施
• LLM 选型：Claude API / 自部署本地模型 / 混合策略
• 多集群场景：URM 如何标识作业来源（集群 ID 字段）
• on-prem vs cloud：客户私有化部署时能否访问 LLM API

---

11. 风险与缓解

风险	影响	缓解
LLM 幻觉导致错误操作	作业丢失/资源浪费	写操作 require confirm；LLM 只做路由不做执行
自研调度器事件流未打通	Phase 2 体验差	已确认进程内事件存在，SSE 通道工作量 2-3 天
LSF/Slurm 轮询延迟	体验代差	通过 agent 工作流 + 模板缓解
上下文窗口膨胀	长任务监控失效	auto-compact + 状态摘要策略

---

12. 附录

12.1 相关文档索引

文档	位置	说明
本文档	doc/Scheduler-Agent-设计文档.md	设计权威来源
集群部署与验证手册	src/docs/chatbot-verification.md	t1/t2/t3 集群启动 + Phase 0-1 验证步骤（2026-08-01）
CLAUDE.md（根目录）	CLAUDE.md	AI 实施向导（含最新进度）
架构图源文件	architecture_overview	Graphviz DOT
架构图渲染	architecture_overview.svg	可视化架构图
架构图生成脚本	generate_diagram.py	diagrams 库
myxce 产品文档	myxce/.kiro/steering/	产品/技术/结构/安全等
feature 规格	myxce/.kiro/specs/	各功能 spec

12.2 关键实现细节备忘

• 认证：apiserver 的 GetUsernameFromToken/isValidToken 已支持 xce_ak_ 前缀，JWT 和 API Key 透明共存（27 处调用点零改动）
• schedulerclient 内存单位：假设 apiserver 返回 MB（HPC 惯例），转 bytes 存入 URM（mbToBytes = 1_000_000 decimal）
• schedulerclient 认证：Authorization header 直接传 token（不拼 Bearer，服务端会 TrimPrefix）
• mcp-server 依赖：github.com/mark3labs/mcp-go@v0.57.0，replace schedulerclient => ../schedulerclient
• 写端点 HTTP 状态陷阱（Phase 1）：ReturnSuccess 恒返回 HTTP 200，逻辑状态在 envelope code 字段（CreateJob→201，ControlJob→202）；只有 ReturnError 才把 HTTP 状态设为错误码。doPost 检查 resp.StatusCode()==200 再 env.Code==expectedCode，不要要求 HTTP 201/202
• run_limit 分钟陷阱（Phase 1）：apiserver CustomInt 解析裸整数为分钟（minutes*60），"HH:MM" 才是秒。schedulerclient 只发 "HH:MM" 字符串；模板 parseWalltimeSeconds 拒绝裸整数避免歧义
• mem_limit wire 格式（Phase 1）：CustomLimit 只接受 "<number> <unit>" 字符串（"4096 MB"），GB=1024MB 二进制；客户端通过 formatMemory 发 MB 字符串，模板解析用 decimal 与 mbToBytes 保持一致
• confirm 无原生支持（Phase 1）：mcp-go v0.57.0 无 RequiresConfirmation，仅 ToolAnnotation 且 NewTool 默认 destructive=true（Phase 0 只读工具因此被误标，已在 Phase 1 修复）；写操作 confirm 用 dry_run review 参数 + destructive 注解实现