智驾专区运行域 使用说明
工具面（一律以运行时为准）
工具按配置注册：宿主只注册已配置的上游 —— 未配置的上游不会出现在你的工具列表里。
所以这里不列工具清单：它是"当前事实"，随上游增减而变，写进文档第二天就可能过期。
工具名与参数一律以运行时看到的为准（tools/list，或先搜一次把工具找出来）；
不要凭印象"补"出一个工具名，也不要编造结果。
本连接器按上游分这几组能力：
| 上游 | 能做什么 | 写侧 |
|---|---|---|
| 作业域（DMS 直连） | 作业模板、作业任务与 Argo 日志、数据文件与采集计划、数据挖掘与多模态检索、本层动作自查 | 有 |
| 主机排障（跳板机） | 连通性探测、白名单只读命令（⚠️ 见下方「> 字符陷阱」）、经确认的写命令与脚本 | 有 |
| TKE 排障 | kubectl 只读工具（对象 / 描述 / 事件 / 日志 / 资源用量） | 无（写操作经主机排障那组） |
| 云资源查询 | 任意只读云 API 动作（Describe / Get / List / Search / Check / Query / Inquire）；写动作只放行服务端白名单里的那几个，未列入的一律拒 | 有（经确认的白名单写动作，须两段式确认 + 幂等） |
| 镜像构建推送 | 服务状态、提交构建、轮询与取消、常驻运行时直发代码 | 有 |
| 库存与客户资源（ADCM） | 可用区机型余量、趋势、告警、预扣、客户已用量 | 无 |
| CLS 日志 / 网络诊断 | 没有专用工具 —— 查询面经云 API 的只读动作可达 | 无 |
⚠️ TKE 没有自己的写工具：
kubectl apply/delete/scale/rollout restart这类写操作， 只能经主机排障那组的写工具在同一台跳板机上执行（就是跑 kubectl 的那台）—— 所以"工具面里没有 TKE 写工具"不等于"集群动不了"。
⚠️
>字符陷阱（主机排障的只读命令）：命令里只要出现>就会被当成重定向拒掉 —— 连struct.unpack(">I")、if v>m这种比较 / 格式符也会命中 ✗。判据不改，改写法： 用int.from_bytes(b, "big")代替">I"，用if m<v代替if v>m。
⚠️ 写侧已开放（2026-10-11 起）：作业域、跳板机、镜像构建三组的写工具默认都在工具面里， 每一次写都必须两段式确认 + 幂等（见下节「写操作」）—— 缺
confirm_text会被拒，且不会触达上游。 跳板机的写命令还受两道硬拦（都拦在两段式确认之前）：A 档 = 服务/启动项类命令直接拒； E 档 = 不可逆操作类（rm -r /、mkfs、dd of=/dev/…、清空防火墙 / 关网卡这类会切断 自己链路的动作）本地直接拒、连确认都不给 —— 这类动作不存在"确认一下就放行"的路径， 别换措辞重试，改成可回退的做法（只删自己那部分、先备份）。
⚠️ 工具面里看不到写工具时，先分清三种原因（别一律说"写侧不开放"）： ① 上游没配 —— 真的没有这个能力；② 令牌缺
mcp.writescope（只有 OAuth 模式有 scope 概念） —— 能力在，但那把令牌被 scope 挡了（写工具不出现在工具面里，调用会得1005/403）： 让用户换一把带mcp.write的授权（重新授权时加上该 scope，或改用静态令牌）； ③ 平台侧的工具索引没带上它 —— 云端 Runtime 出现过"连接器 ready 但工具进不了模型的可用列表"， 这时谁都调不到，如实说明即可，不要重试、不要编结果。
库存与客户资源（ADCM，只读）
判断「部署到哪个可用区」的顺序（具体工具名以运行时为准）： 先看资源告警（总量够、但某机型告警时仍会排不上）→ 再看该区该机型的可用量 → 看趋势 （照这个速度还能撑多久）→ 别忘了预扣会占用可用量 → 最后对客户已用量。
⚠️ 这一族只有只读（上游第三、五章没有写接口，也没有要确认的写操作）。 报「凭据被拒 / 不可达」时，先调那一族的用户信息工具，把链路问题与参数问题分开。
镜像构建推送（宿主直连构建机，不经窄桥）
把代码 / 镜像地址变成推到上海侧仓库的容器镜像（专区靠仓库的实例同步分发）。
动线（工具名以运行时为准）：
- 先看服务状态 —— 仓库凭据配没配、docker 与对象存储依赖在不在。
- 提交构建 ——
source四类：git（代码地址，monorepo 要给subdir）·object（交接桶里的 代码包，大包走这条）·image（既有镜像，拉—重打—推）·upload（宿主侧先流式上传）。 立即返回job_id。私有来源（git/ 私有 registry）还要带凭据引用：引用名由管理员在 服务侧登记，凭据值不经过对话；不确定登记过没有，先按tools/list找那一族的查询工具看一眼。 - 轮询与拉日志 —— 构建是分钟级，别同步等；日志要增量拉。
- 需要时取消 —— 只能取消尚未结束的任务。
- 调试期免重建 —— 常驻运行时里同一
session_id复用同一个容器，改代码直接跑 （文件落在/work/code/下；容器工作目录是/work，所以命令要写全路径）； 跑通之后再用第 2 步固化成镜像。
⚠️ 代码包不要塞进工具参数（工具参数由模型生成，服务侧 JSON 上限默认 1 MB）： 大包先在宿主侧流式上传或放进交接桶，再以
source.kind=object提交。 只要"代码进专区"、不出镜像时（专区作业按对象键读代码）：上传后走那一族的对象推送， 落到专区对象桶的指定对象键上 —— 桶由服务端配置（你只给键）；把返回的bucket+ 键报给用户， 作业侧按它读 ✓。 宿主侧上传里，包大了还要再分片（开会话 → 按offset逐片追加 → 提交收尾）：一次性吐几十 KB 的 base64 本身就不可靠 ✗；单片 / 合计上限与会话有效期按工具面自述取，超上限改走交接桶 ✓。⚠️ 对象推送会"自动加一段前缀"：你请求时给的键不等于最终落点，服务侧会加上自己那一段 —— 以推送回执里的完整键为准，作业侧按它写挂载前缀，别按你请求时写的那个 ✗。 文件名只允许字母数字与
._-，且首位必须是字母数字（_keep这类会被拒）。 推完要三方核对（本地 / 挂载点 / 回执）：COS 客户端有本地缓存，"脚本说写入成功" 不等于对象已落桶 —— 在另一台机器的挂载点上ls到才算数 ✓。
写操作：两段式确认 + 幂等（人工复核就在这一步）
写工具都是两段式，照这个顺序用，别跳：
- 先不带
confirm_text调一次 —— 返回summary（这一步要做什么）与应原样回传的confirm_text。 - 把
summary念给用户（带对象与影响范围），等他明确同意。 - 带原样的
confirm_text再调一次 —— 参数必须与第一次完全一致；同参数只会执行一次（幂等键在服务端）。
- 术语统一：确认串（
confirm_text）+ 幂等键 —— 不要叫"令牌"。 - 参数变了就重新确认：中途补参数（补
cluster_name、补params）会换一个新确认串 ⇒ 回到第 1 步。 - 不要猜
confirm_text；也不要因为第二次调用"没反应"就反复重试（幂等键会保持同一次执行，重试只污染判断）。 - ⚠️ 跳板机写命令另有两道前置：A 档（服务 / 启动项类：
systemctl restart/stop/reload、reboot、crontab）与 E 档（不可逆操作类：rm -r /、mkfs、dd of=/dev/…、 清空防火墙 / 关网卡），拦在两段式确认之前 —— 命中时连summary都不会生成； 别换措辞重试（这类动作没有"确认一下就放行"的路径）。
作业动线（DMS 语义）
排查从"结果"往回走，别从猜开始：
dms_task_list筛出目标作业（关注状态码）。dms_task_get(id)看status、argoWorkflowName与各节点配置。dms_task_log(id)取 Argo 工作流日志 —— 失败原因基本都在这里。
状态码是固定取值，不要自己编：0 待调度 / 1 已下发 / 2 执行中 / 3 成功 / 4 失败 / 7 下发失败。
要新建作业时的顺序：先 dms_data_file_list 拿 file_id，
再 dms_template_list 选 template_id，然后 dms_task_create → dms_task_execute（建完不会自动执行，
这是 DMS 的接口形状）。
⚠️ 模板里的
memoryLimit/memoryRequest必须带Gi单位（如"4Gi"）； 模板更新只影响之后创建的任务，不追溯已建任务。
⚠️ 下发是异步受理：
status=0不等于"没生效"。刚下发（或重试）后编排器拉起有延迟， 立即回读大概率还停在0（待调度）—— 判读要等 1～2 分钟再看status是否离开0， 或用只读 kubectl 看任务 Pod 是否被拉起。不要回读一次status=0就下"未生效"的结论。
运维细节
- 端点级的注意事项与读错误判读，问
adc_capabilities（只读、不联网）—— 它回答： 本层替注入了什么、上游路径里的历史拼写、哪一族是 REST 形状、哪些接口本层不持有 schema， 以及失败时怎么区分「没查到」（上游业务的正常回执，带原文code/msg）与 「查不了」（本层失败：上游超时 / 配置缺失 / 动作不在白名单）。 ⚠️ 这些是代码级事实，所以只在服务端回答、不进包（进包就得跟着升版重发，且很容易过期）； 包内文本只留判据：两类失败下一步完全不同，都别编一个结果出来。 ⚠️ 工具面里没有adc_capabilities时（本地形态的包不在本仓库）—— 按上面这条判据判读。
失败定位
先 dms_task_get 看状态与节点 → dms_task_log 取日志 → 按现象定位环节：
| 现象 | 最可能原因 |
|---|---|
| 显存不足 / OOM | 批次过大或资源与节点不匹配 |
| 数据路径不存在 | 挂载路径与模板配置不一致 |
| 依赖版本冲突 | 镜像基线与代码要求不一致 |
| 启动即退出 | 入口命令错误或缺环境变量 |
| 超时被回收 | 资源不足或存在死循环 |
状态停在 7 下发失败 | 调度侧问题，不是作业自身失败 |
区分「没跑成」与「跑了但结果不好」 —— 两类问题的下一步完全不同。
硬约束
- 不静默重试：失败先定位，再由用户决定是否重跑（
dms_task_retry可用，但不等于可以替你决定重跑）。 - 别凭印象编 Id：模板 Id、任务 Id、
file_id都要从查询工具拿到。 - 引用日志只取必要片段：日志可能很长、可能含内部路径 —— 长度本层不裁剪。
- 凭据类字段会被自动剥掉：模板配置、返回值与命令输出在返回给你之前，已按「键名 /
name-value配对 / 高置信模式」剥掉凭据（AKID…、sk-…、JWT、PEM 私钥、password=…这类）。所以某字段拿不到不等于它不存在 —— 先考虑是被裁剪了，别据此猜值，也别反复重试。 - 写操作必须用户确认：所有写工具都会改真实状态（作业的建 / 下发 / 重试、模板复制、
主机命令与脚本、镜像构建与取消、常驻运行时跑代码）—— 缺
confirm_text不得调用， 也不得替用户"先做了再说"。
风险（如实告知，别淡化）
⚠️ DMS 的写接口当前没有鉴权（文档原话是"内网可达即可调用"）。本形态的写侧已开放， 所以"连接器层隐藏"那道老护栏已经不存在 —— 现在的门槛是工具层的两段式确认 + 幂等 （再加跳板机的危险动词黑名单 / A 档硬拦）。在 DMS 侧补上鉴权之前，不要把本形态的写能力当作用户已授权； 用户没说清对象与影响范围时，也不要替他确认。
