tione-commander
TI-ONE 控制面的统一入口：一个 CLI（scripts/tione.py，仅需 Python 3.9+ 标准库）、一张动作注册表、一套风险闸门。
覆盖腾讯云 TI-ONE 公开 API 的全部 74 个动作。能做的都能做，但每一步变更都留痕、可预演、可拒绝；它不是无约束的自动驾驶。
公开 API 做不到、需要在控制台完成的事：创建资源组、CVM 纳管与解除纳管、销毁节点、内置大模型的推理模板查询、客观评测。遇到这些需求，直接告诉用户去控制台，不要尝试绕过。
铁律（先读，违反即停）
- 默认只读。凡 R1 及以上动作，先用不带
--execute的命令做预演，把输出的 plan（动作、地域、参数、风险、费用标记、确认码）原样展示给用户。 - R2/R3 必须取得用户对这一份 plan的明确同意后，才能带
--execute --confirm <确认码>重跑。R3 另需--i-understand。不得自行代用户确认，不得复用别的 plan 的确认码。 - 确认码绑定动作、地域、端点、UIN 与参数。参数改了，旧码作废，必须重新预演。
- 不填默认值：资源组 ID、模型版本、服务名必须由用户给出或由只读查询得到。
- 模板里的
<...>占位符没替换干净，闸门会拒绝。 - 默认输出已脱敏（AuthToken、临时凭证等）。仅当用户明确要原值时才加
--reveal，且不要把原值写进文件、日志或回复。 - 破坏性动作前先备份可导出的信息（
describe结果存档），并优先选更轻的替代：停止代替删除。 - 每次尝试（预演、拦截、执行）都写入审计日志
~/.workbuddy/tione-commander/audit.jsonl。被问到“做过什么”时用tione.py audit，不要凭记忆回答。
快速开始
cd <本 Skill 目录>/scripts
export TENCENTCLOUD_SECRET_ID=... TENCENTCLOUD_SECRET_KEY=... # 建议子账号 + 最小权限
python3 tione.py selftest # 离线自检（本地模拟，不碰真实账号），应输出 SELFTEST OK
python3 tione.py profile add sh --region ap-shanghai --readonly # 只读 profile（不存任何密钥）
python3 tione.py doctor --profile sh --ping # 一次真实只读调用，验证凭证与权限
细节见 references/setup.md。全局参数（--profile --region --endpoint --reveal）写在子命令之后。
命令速查
| 目的 | 命令 |
|---|---|
| 看全部动作与风险 | tione.py actions [--group service] [--risk R3] [--search kw] |
| 只读查询 | tione.py describe DescribeTrainingTasks --filter "Name=Status,Values=RUNNING;PENDING" --limit 20 |
| 翻页取全 | tione.py describe DescribeBillingResourceGroups --all |
| 取一个字段做串联 | tione.py describe DescribeTrainingTask --params '{"Id":"train-x"}' --select TrainingTaskDetail.LatestInstanceId |
| 智能日志/事件 | tione.py logs train-x --key NCCL、logs ms-x --events、logs nb-x（自动换成实例级 ID） |
| 诊断 | tione.py diagnose training train-x、diagnose service ms-x |
| 盘点与费用泄漏 | tione.py inventory |
| 模板列表 | tione.py templates |
| 预演变更 | tione.py call CreateModelService --template create-service-vllm-custom-image --set ServiceGroupName=demo ... |
| 执行变更 | 同上，加 --execute --confirm <码>，R3 再加 --i-understand |
| 导出热力图 | tione.py heatmap --out ~/Desktop/tione-heatmap.html（离线，无需凭证） |
| 热力图叠加实时快照 | tione.py heatmap --live --redact --out live.html（只读盘点；--redact 遮蔽资源 ID） |
| 热力图其它格式 | --format md（技术栈文档）/ --format json；--scenario d 与 --view heat 设定初始场景与视图 |
| 控制台链接 | tione.py console service ms-x |
| 审计 | tione.py audit --tail 20 |
--set 支持点路径与 JSON 字面量，例如 --set Resources.Gpu=100 --set ScheduledAction.ScheduleStop=true。--params 可传 JSON 串或 @文件。
按意图选流程
- 训练任务失败/卡住/慢：
diagnose training→ 看 findings 与 evidence → 需要更多日志时logs。判据见references/playbooks.md第 1 节。 - 服务启动慢/不就绪/异常：
diagnose service；常见根因是权重加载、Readiness 探针、--max-model-len过大导致 OOM。见 playbooks 第 2 节。 - 创建推理服务：先
describe DescribeBillingResourceGroups选资源，再选assets/requests/的模板预演、确认、执行，随后轮询服务组状态；创建时设置定时停止。见 playbooks 第 3 节。 - 灰度发布：
modify-service-weights模板（R2）。 - 安全相关：鉴权开关、AuthToken 增删、子账号 Linux 用户映射都是 R2/R3，必须逐项确认。
- 费用泄漏巡检：
inventory，看alerts。
能看到什么，看不到什么
这个 Skill 经控制面 API 取得配置、状态、实例级日志与 K8s 事件。它拿不到数据包、NCCL 带宽、单步训练耗时、请求在 Pod 间的真实跳点、GPU 微观利用率。要回答这些问题，需要 Pod 内日志（如 NET/IBext/GDRDMA 判断 RDMA 是否生效）、profiler 或监控系统。回答时区分“API 已确认”“官方文档所述”“工程推断”，推断必须写明依据。
参考资料（按需读取，不要一次全读）
| 文件 | 何时读 |
|---|---|
references/capability-map.md |
查某个动作的风险与标记（自动生成，tione.py actions 为准） |
references/safety.md |
解释闸门规则、处理被拦截的操作 |
references/setup.md |
配凭证、权限、地域 ID、profile |
references/playbooks.md |
训练/推理故障排查、创建服务、费用泄漏的完整步骤 |
references/api-parameters.md |
查 Filters 枚举、状态枚举、必填参数、控制台链接与地域 ID |
references/architecture.md |
平台技术栈分层、各组件的大白话解释与证据等级；回答“底层怎么实现”时用 |
assets/requests/*.json |
已脱敏的请求模板，tione.py templates 列出 |
data/sdk_api_meta.json |
官方 SDK 各动作的说明与请求字段，用于核对参数名 |
输出 heatmap（热力拓扑）
python3 scripts/tione.py heatmap --out ~/Desktop/tione-heatmap.html # 离线：不联网、不要凭证
python3 scripts/tione.py heatmap --live --redact --out ~/Desktop/tione-live.html # 叠加账号的实时只读快照
python3 scripts/tione.py heatmap --format md --out tione-stack.md # 技术栈文档
页面含 10 层 77 个组件、126 条链路、9 个运行场景（外加全景）。点击任意组件或连线，右侧先用大白话解释“这是什么 / 它在系统里干什么 / 打个比方”，再列出数据从哪来、流向哪（可点击跳转），最后是带证据等级的技术细节。组件解释写在 data/explain.json，新增组件时必须同时补解释，否则校验不通过。视图可切换：热度（场景模拟）、实时（仅 --live）、无叠加。
给用户解释时必须分清三种数据：
1. 拓扑组件与链路：来自官方文档、接口字段与开源框架资料，每条带证据等级（O 官网 / S 接口字段 / F 框架 / G 推测），G 级附依据。
2. 光点与热度：场景模拟，不是监控数据。
3. 实时视图：只读 Describe* 盘点得到的资源组占用率、任务/服务/开发机数量与告警；热度按页面顶部说明归一化，数字以文字为准。它不含 NCCL 带宽、单步耗时、请求跳点等接口拿不到的信息。
--live 生成的文件含账号内资源 ID（权限 0600）；要分享先加 --redact。拓扑数据在 data/topology.json，改动后运行 python3 scripts/build_topology.py --all <输出.html> 校验并重生成。
