fix(schedulerclient): node memory_bytes_total no longer ×1e6 (bug-1514)

The apiserver's host max_mem is already in bytes (the worker reads
sysinfo().totalram × mem_unit → bytes and passes it through unchanged via
controller.capnp), but ListNodes treated it as MB and multiplied by
mbToBytes, inflating each node's reported memory to ~8.2e15 (~7.3 PiB).
Now reports the raw bytes (~7.7 GiB per node).

- httpclient.go: drop ×mbToBytes for node max_mem; clarify mbToBytes is
  job-submit-path only (job max_mem is never populated → stays 0)
- ordermap_test.go: correct assertion that had encoded the buggy value
- httpclient_test.go: regression test TestListNodeMemoryBytesKeepsByteUnit
- buglog.json: bug-1514 + close-tags for the bug-1494 family (prior session)

Also add MCP demo deliverables:
- docs/claude-code-demo-guide.md: live Claude Code demo guide (7 scenes)
- docs/mcp-demo-design.md: leadership demo design
- docs/mcp-demo-run.py: add --slow/--color flags for screen recording

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
lei.chen 2026-08-22 14:58:56 +00:00
parent bbe8ed3335
commit 06887985b4
7 changed files with 423 additions and 36 deletions

View file

@ -0,0 +1,90 @@
# XCE MCP 演示设计(面向领导与同事)
## 目标
展示「自然语言操作 HPC 集群」:不用命令行、不用记语法,通过 MCP 让 AI 助手直接查询、提交、诊断、调整作业。观众无需理解 XCE/集群内部机制,只需看到「一句话 → 集群动作 → 结果」。
## 叙事主线(一个工程师的日常)
> 一位工程师("我")用对话的方式管理一批计算作业:查状态 → 看为什么排队 → 提交新作业 → 观察运行 → 诊断失败 → 清理。全程用自然语言,AI 助手调用集群工具完成。
## 环境与前置
| 项 | 状态 |
|---|---|
| 集群 | t1/t2/t3(3 计算节点),controller/scheduler/apiserver 健康 |
| MCP server | `/tmp/xce-mcp`(最新构建)|
| API key | `export XCE_API_KEY=<mcp_operator key>`(90 天,见 `/tmp/xce_apikey`)|
| 演示机 | 任意可 ssh 到 t1 的终端,用 python 驱动 MCP stdio 或直接对话 |
**演示前清理**:删除历史 EXIT/DONE 作业(保持列表干净),确保 worker 在线。
## 演示流程(约 10 分钟)
### 场景 1:总览——"我的集群现在怎么样"(2 分钟)
- **问**:「看看集群现在有哪些节点、资源怎么样」
- **工具**:`scheduler_cluster_metrics` + `scheduler_list_nodes`
- **展示**:3 节点在线、总核数、空闲资源,直观的集群健康度
- **讲解点**:AI 能读懂集群状态并总结,不用查文档
### 场景 2:作业队列——"都有什么作业在跑/排队"(1 分钟)
- **问**:「列出当前所有作业,特别是排队的」
- **工具**:`scheduler_list_jobs`
- **展示**:作业列表(名字/状态/队列/提交人),PEND 的作业一眼可见
- **讲解点**:MCP 把「作业列表」这种高频操作变成一句话
### 场景 3:为什么排队——"这作业为什么还没跑"(2 分钟)
- **问**:「有一个作业一直 pending,帮我看看为什么」
- **工具**:`scheduler_pend_reasons`(bjobs -p 等价)
- **展示**:返回「waiting: no host matches... host t1: match_fail」可读解释
- **讲解点**:**核心价值**——以前要翻日志猜原因,现在 AI 直接给出原因(配额/资源/匹配)
### 场景 4:提交作业——"帮我把这个任务跑起来"(2 分钟)
- **问**:「提交一个 sleep 60 的作业到 xce 队列」
- **工具**:`scheduler_submit`(先 dry_run 预览 → 再真实提交)
- **展示**:先展示「将要提交的规格」,确认后提交,返回 jobid
- **讲解点**:写操作有**预览 + 确认**安全机制,不是盲目执行
### 场景 5:等待完成——"帮我等这个作业跑完"(1 分钟)
- **问**:「等刚才那个作业跑完」
- **工具**:`scheduler_wait_job`
- **展示**:阻塞等待 → 返回最终状态(succeeded)
- **讲解点**:AI 能「等待并汇报结果」,交互式而非一次性
### 场景 6:资源建议——"帮我估算一下要多少资源"(1 分钟)
- **问**:「我要跑一个 8 小时的科学计算,帮我看看要多少核/内存」
- **工具**:`scheduler_suggest_resources` + `scheduler_estimate_wait_time`
- **展示**:根据集群容量给出建议核数/预估等待
- **讲解点**:AI 结合集群实时状态给建议,不只是套公式
### 场景 7:清理——"把不需要的作业都取消"(收尾,1 分钟)
- **问**:「取消刚才提交的那个测试作业」
- **工具**:`scheduler_cancel`
- **展示**:干净收尾,展示「有确认机制」的安全感
- **讲解点**:破坏性操作有保护
## 讲解要点(给观众的价值主张)
1. **效率**:5 个常用操作(查/排/看/提/等)从「命令+文档」变成「一句话」
2. **透明**:PEND 原因、资源建议都有可读解释,不再黑盒
3. **安全**:写操作(提交/取消/挂起)先预览、需确认,不会误操作
4. **可扩展**:MCP 协议标准,未来可接更多集群操作
## 演示脚本(MCP stdio 驱动,python)
见 `mcp-demo-run.py`(同目录)——自动执行场景 1-7,输出每一步的「用户问 → 工具 → 结果」。
## 备选/延伸(时间充裕时)
- **多作业调度**:提交 3 个作业,展示负载均衡(各节点分配)
- **故障演示**:模拟一个作业失败(命令故意报错),`scheduler_analyze_failure` 诊断
- **挂起/恢复**:`scheduler_hold`/`release` 演示管理员控制
## 风险与规避
| 风险 | 规避 |
|---|---|
| 演示中作业意外失败 | 用 `sleep 60` 这类可靠命令,避免真实计算 |
| 网络/集群抖动 | 演示前确认 3 节点 OK + worker 在线 |
| 观众不懂 HPC | 全程用「作业/排队/节点」类比「任务/等待/机器」,不讲协议 |
| key 失效 | 演示前重新生成 mcp_operator key |