@volcengine/ark-cli-linux-x64 1.0.48 → 1.0.49-prerelease.4bb99e52eb83
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/arkcli-linux-amd64 +2 -2
- package/manifest.json +16 -44
- package/package.json +1 -1
- package/skills/arkcli-agent/SKILL.md +4 -1
- package/skills/arkcli-agent/references/agent.md +43 -0
- package/skills/arkcli-agent/references/evals.md +15 -0
- package/skills/arkcli-agent/references/interfaces-gaps.md +77 -0
- package/skills/arkcli-agent/references/session-files.md +12 -11
- package/skills/arkcli-helper/SKILL.md +19 -7
- package/skills/arkcli-helper/references/arkcli-helper.md +93 -5
- package/skills/arkcli-helper/references/evals.md +6 -2
- package/skills/arkcli-vmp/SKILL.md +50 -0
- package/skills/arkcli-vmp/references/alert.md +62 -0
- package/skills/arkcli-vmp/references/capability-model.md +39 -0
- package/skills/arkcli-vmp/references/capacity.md +25 -0
- package/skills/arkcli-vmp/references/collect.md +50 -0
- package/skills/arkcli-vmp/references/evals.md +36 -0
- package/skills/arkcli-vmp/references/snapshot.md +7 -0
- package/skills/arkcli-vmp/references/top.md +9 -0
- package/skills/arkcli-vmp/references/watch.md +32 -0
- package/skills/arkcli-vmp-workflows/SKILL.md +100 -0
- package/skills/arkcli-vmp-workflows/references/alert-provision.md +75 -0
- package/skills/arkcli-vmp-workflows/references/capacity-review.md +58 -0
- package/skills/arkcli-vmp-workflows/references/daily-digest.md +91 -0
- package/skills/arkcli-vmp-workflows/references/evals.md +35 -0
- package/skills/arkcli-vmp-workflows/references/feishu.md +62 -0
- package/skills/arkcli-vmp-workflows/references/incident-drilldown.md +52 -0
- package/skills/arkcli-vmp-workflows/references/release-compare.md +80 -0
- package/skills/arkcli-vmp-workflows/references/rollout-watch.md +78 -0
- package/skills/arkcli-vmp-workflows/references/run-record.md +59 -0
- package/skills/arkcli-vmp-workflows/references/scheduler.md +70 -0
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
## 覆盖目标
|
|
4
4
|
|
|
5
5
|
- 区分真人 TTY Harness 矩阵与 Agent 可执行的非交互子命令。
|
|
6
|
+
- 用户两次运行真人向导之间开通个人套餐或获分配团队席位时,引导再次运行 `arkcli helper`;在线查询成功后会自动补建 profile,本次即可选。已回收的个人套餐和已撤销的团队席位应显示原因、跳过选择,续费后复用原 profile;查询失败时提示状态待确认。
|
|
6
7
|
- 区分服务端权益开关与所选 AI Agent 的本地配置状态。
|
|
7
8
|
- 区分“本次配置 Checkbox”与“当前配置状态”,并锁定 disabled 行不可选择。
|
|
8
9
|
- 保持计费写操作确认、团队权限范围和未知 Harness fail-safe。
|
|
@@ -23,7 +24,7 @@
|
|
|
23
24
|
|
|
24
25
|
- 仅查询套餐持有、购买、续费或席位列表时转 `arkcli-plans`。
|
|
25
26
|
- 仅查询模型目录或能力推荐时转 `arkcli-models`。
|
|
26
|
-
- Agent 自动化不得尝试发送按键操纵 `arkcli helper` TTY 菜单;应选择 `helper configure/mcp/supabase/list/reset` 的最具体子命令。
|
|
27
|
+
- Agent 自动化不得尝试发送按键操纵 `arkcli helper` TTY 菜单;应选择 `helper configure/mcp/supabase/list/status/reset` 的最具体子命令。
|
|
27
28
|
|
|
28
29
|
## Guard / 守卫
|
|
29
30
|
|
|
@@ -46,6 +47,10 @@
|
|
|
46
47
|
|
|
47
48
|
```bash
|
|
48
49
|
arkcli helper list --format json
|
|
50
|
+
arkcli helper status codex --format json
|
|
51
|
+
arkcli helper configure codex --profile <agent-plan-profile> --model <model-id>
|
|
52
|
+
arkcli helper configure codex --profile <platform-profile> --endpoint <ep-id>
|
|
53
|
+
arkcli helper configure pi --profile <plan-profile> --model <model-id>
|
|
49
54
|
arkcli helper configure codex --profile <agent-plan-profile> --model <model-id> --with-mcp
|
|
50
55
|
arkcli helper configure codex --profile <agent-plan-profile> --model <model-id> --with-mcp --keep-native-websearch
|
|
51
56
|
arkcli helper configure codex --profile <agent-plan-profile> --model <model-id> --with-mcp --with-supabase
|
|
@@ -56,7 +61,6 @@ arkcli helper mcp codex --profile <agent-plan-profile> --capability datapro
|
|
|
56
61
|
arkcli helper mcp codex --profile <agent-plan-profile> --capability web-search
|
|
57
62
|
arkcli helper mcp codex --profile <agent-plan-profile> --capability agent-memory --ov-resource <database-name>
|
|
58
63
|
arkcli helper mcp codex --profile <agent-plan-large-or-max-profile> --capability cua
|
|
59
|
-
arkcli helper configure pi --profile <plan-profile> --model <model-id>
|
|
60
64
|
```
|
|
61
65
|
|
|
62
66
|
`arkcli helper` 无子命令的 Harness 矩阵只允许真人在 TTY 中运行,不纳入 Agent 自动执行的 happy path。
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: arkcli-vmp
|
|
3
|
+
description: 编排 ARK 可观测任务:多 Endpoint 放量观察、发布前后对比、十四天历史峰值和容量证据分析。用户说“盯着放量”“比较上线前后”“过去两周容量够不够”“找最忙接入点”时使用。组合资源清单、VMP 采集与诊断,输出可追溯证据和结论;告警写入走 raw action,自动调度尚未支持。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ARK 可观测任务
|
|
7
|
+
|
|
8
|
+
先读取并遵循 `../arkcli-shared/SKILL.md`。
|
|
9
|
+
|
|
10
|
+
目标是完成用户的观察或分析任务。CLI 提供可靠查询、时间对齐、分片、统计和输出;由本 Skill 决定范围、执行顺序、条件分支、证据产物和完成标准。所有采集命令都在 `arkcli doctor monitor` 下;单 Endpoint 诊断仍用 `arkcli doctor infer-endpoint`。
|
|
11
|
+
|
|
12
|
+
## 适用场景与参考
|
|
13
|
+
|
|
14
|
+
| 用户目标 | 执行流程 | 参考 |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| 放量期间盯住多个 Endpoint | 明确资源和阈值 → 基线 → 有限时长观察 → 异常诊断 → 报告 | [放量观察](references/watch.md) |
|
|
17
|
+
| 发布前后是否退化 | 固定两个等长不重叠时间段 → `doctor monitor compare` → 检查 coverage/流量守卫 → 解释 pass/violation/inconclusive | [采集与对比](references/collect.md) |
|
|
18
|
+
| 过去两周峰值、容量是否足够 | 固定十四天范围 → 分片一分钟采集 → 峰值和缺口 → 核对配额口径 → 结论 | [历史容量](references/capacity.md) |
|
|
19
|
+
| 现在有什么异常/最忙资源 | 确定 EP 集合 → 摘要或排行 → 根据证据下钻 | [快照](references/snapshot.md)、[排行](references/top.md) |
|
|
20
|
+
| 配告警、每天定时检查 | 读模板与现有规则;写入走 raw action 并回读;定时检查转 workflow Skill | [告警与调度](references/alert.md) |
|
|
21
|
+
|
|
22
|
+
需要把证据推送到飞书、写入文档/看板、注册定时任务,或把多个观察/对比/巡检任务串成一条持续工作流时,转到 [`../arkcli-vmp-workflows/SKILL.md`](../arkcli-vmp-workflows/SKILL.md)。本 Skill 只负责一次性观察与分析。
|
|
23
|
+
|
|
24
|
+
## 反唤起信号
|
|
25
|
+
|
|
26
|
+
单纯查 Token 用量或账单分别用 arkcli-usage / arkcli-billing;已有明确故障、只需诊断时用 arkcli-doctor;创建或更新 Endpoint 用部署/Endpoint Skill。不要为了使用监控命令而扩大这些任务。
|
|
27
|
+
|
|
28
|
+
## 执行顺序与守卫
|
|
29
|
+
|
|
30
|
+
1. 确定 profile、明确的 Endpoint 集合、时间范围和用户判据。用户指定 EP 时直接使用。用户说“全项目”时,先读 `../arkcli-infer-endpoint/SKILL.md`,用控制面清单解析本 profile 可见的所有分页,再把明确 ID 传给采集;不要用共享 VMP workspace 代替项目范围。保存清单和解析时间。单批最多 50 个 EP,多批必须共享同一 start/end。
|
|
31
|
+
2. 需要核对身份范围时按 shared 分别执行 `arkcli auth status` / `arkcli auth whoami`,直接检查原始结果,保存脱敏后的产品、region、project 信息;字段不足时标明范围尚未核实。`profile show` 可能同步 Key 并回写配置,不能当作普通只读身份检查。查询只读解析已绑定的 workspace。未登录或凭证过期时转到 `../arkcli-auth/SKILL.md`,缺绑定或权限时按实际错误给出下一步;创建/绑定是另一个有副作用的操作,不假称“采集已完成”。
|
|
32
|
+
3. 选择固定时间或相对 window。历史分析和前后比较优先 start/end;固定时间需 RFC3339 整秒。`window` 是查询跨度,`step` 是取点间隔,`range` 是每点统计回看窗口,三者独立。十四天写 `336h`,不是 `14d`。用 [采集契约](references/collect.md)。
|
|
33
|
+
4. 将 JSON/JSONL 保存到本次任务目录,连同用户目标、资源清单、执行命令和结论报告。基础层负责所有统计、分片、去重和单位换算;不要临时写鉴权、PromQL 拼接或粗化峰值的脚本。
|
|
34
|
+
5. 检查 collection.status、每个结果的 status/coverage 和 queries。`available` 只表示请求网格上的有限采样齐全;它不证明源数据完整,也不表示健康。`partial`/`no_data`/`failed` 都不能填零。真实 RPM=0 只说明采样点观察到零流量;没有错误率/时延时不能据此宣称服务通过验证。
|
|
35
|
+
6. 指标异常时,先读 `../arkcli-doctor/SKILL.md`,按其真实入口诊断对应 EP。报告把观测事实、假设、诊断证据和处置建议分开。未经用户授权不要直接改配额、切模型或停止 EP;告警写入必须走 [告警](references/alert.md) 的"确认 + 回读"协议,不能只凭采集结果直接创建。
|
|
36
|
+
7. 完成时提供简短结论(达到判据 / 违反判据 / 不可判定),逐 EP 证据、时间、单位、覆盖率、峰值时间、缺口和下一步。阈值未提供时可做描述性观察,不自行宣布“放量通过”。
|
|
37
|
+
|
|
38
|
+
## 能力边界
|
|
39
|
+
|
|
40
|
+
- `collect` 默认采集 RPM、错误率、请求 E2E P99、输入/输出 TPM。**E2E P99 不是 TTFT**;当前没有经过核实的 TTFT 采集契约。
|
|
41
|
+
- 错误率是逐 EP 比例;sample_mean 是观测点平均值,不是全时段按请求加权的错误率。P99 的峰值是“每点 P99 的峰值”,不是整个十四天所有请求的 P99。
|
|
42
|
+
- `compare` 逐 EP 输出两个等长窗口的 `sample_mean`/峰值差异与 `pass|violation|inconclusive`;阈值随输出回显。`sample_mean` 不是按请求加权的错误率,P99 的均值不是全时段 pooled P99;`--min-rpm-ratio` 只是流量塌陷守卫,不代表流量下降一定是故障。
|
|
43
|
+
- `errors` 聚合逐 EP 错误码 Top N、请求量、错误率和规则化建议;`hints` 是建议不是根因。有流量但零错误是 `available` + `codes: []`;无流量才是 `no_data`。
|
|
44
|
+
- `capacity` 计算逐 EP TPM 利用率:`peak_total_tpm / purchased_tpm`,`>=80%` 为 warning、`>=100%` 为 critical;配额缺失或覆盖不足时为 `inconclusive`。`assumptions[]` 说明配额来自 completion 指标,账单口径以控制台为准。`--include-free-quota` 附带模型级免费额度余量(同模型 EP 共享,不是单 EP 独占);pricing 不可用时降级为 `unavailable`,不影响容量结论。
|
|
45
|
+
- 所有 monitor 命令支持隐式范围 `--mine/--model/--name-regex/--status`(与 `--endpoint` 互斥):启动时解析一次控制面清单,结果写入 `scope`;超过 50 个截断并记录 `skipped[]`,零匹配直接报错。`--mine` 在可取得 ARK IAM UserID 时走服务端 createdBy 标签过滤,降级身份走客户端用户名后缀匹配,不降级为全项目扫描。watch 不会在运行中刷新范围。
|
|
46
|
+
- `watch --alert-on` 在每轮采样后做确定性阈值判断,`--alert-for` 要求连续 N 轮越界;只在 firing/resolved 状态切换时输出事件,结束时仍有未恢复告警则非零退出。这是有界会话内的判断,不是常驻告警规则。
|
|
47
|
+
- watch 是有界前台观察,输出逐轮 JSONL 和 end 记录;退出或中断后不会继续运行。没有常驻告警、计划调度或恢复运行的承诺。
|
|
48
|
+
- 采集与告警读取是只读;`doctor monitor` 的 workspace 自动绑定和告警写入是显式写操作,必须展示影响并回读。告警写操作只通过 `arkcli api vmp.*` 原始 action 提供,不挂 shortcut。
|
|
49
|
+
- 告警能力只覆盖**标品 CN 的 VMP 告警**。详见 [能力模型](references/capability-model.md)。
|
|
50
|
+
- 不存在 `doctor monitor workspace list`、`--since`、`--output`、`--once`、`--threshold`。使用 `--workspace-id`、`--window`/`--start --end` 和全局 `--format`。只读采集没有 `--dry-run`。
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# 告警:读取、写入与调度边界
|
|
2
|
+
|
|
3
|
+
适用范围:**标品 CN 的 VMP 告警**。分工见 [能力模型](capability-model.md)。
|
|
4
|
+
|
|
5
|
+
## 只读命令(shortcut)
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# 列工作区下的告警规则组;不传 --workspace-id 时只读解析 telemetry 绑定
|
|
9
|
+
arkcli doctor monitor alert list [--workspace-id ws-xxx] [--template-id tpl-xxx] [--page-size 50]
|
|
10
|
+
|
|
11
|
+
# 列出 CN 区域内置告警模板目录(本地常量,不访问后端)
|
|
12
|
+
arkcli doctor monitor alert templates
|
|
13
|
+
|
|
14
|
+
# 查看单个模板详情:PromQL、默认阈值、版本
|
|
15
|
+
arkcli doctor monitor alert template --template-id b2876e3d-c52b-41d6-9b41-1b020fc7b2aa
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`alert list` 输出 `workspace_id` / `total` / `items[]`;每条规则组含 `id`、`name`、`template_id`、`template_version`、`notify_policy_id`、`tags[]`(`ark_endpoint_<id>` 是控制台反查 endpoint 告警的约定 key)、`rules[]`(`enabled` 与各档 `levels`)。未绑定工作区时命令报 `no VMP workspace bound to ark telemetry`,不静默返回空。
|
|
19
|
+
|
|
20
|
+
## 写入(原始 action,无 shortcut)
|
|
21
|
+
|
|
22
|
+
写操作不挂 shortcut,避免在 CLI 复刻控制台表单校验;需要批量 / 幂等编排时用 `arkcli api`:
|
|
23
|
+
|
|
24
|
+
| 动作 | 用途 |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `vmp.create_alerting_rule_group` | 从模板创建规则组(替换 `Variables` / `Tags`) |
|
|
27
|
+
| `vmp.update_alerting_rule_group` | 全量更新;关闭告警把 `Items[].Enable` 置 `false` |
|
|
28
|
+
| `vmp.delete_alerting_rule_group` | 从 VMP 删除规则组(不可恢复) |
|
|
29
|
+
| `vmp.tag_resources` / `vmp.untag_resources` | 打 / 摘 `ark_endpoint_<id>` 标签 |
|
|
30
|
+
| `vmp.list_notify_policies` / `vmp.create_notify_policy` / `vmp.update_notify_policy` | 通知策略读写 |
|
|
31
|
+
| `vmp.list_contact_groups` / `vmp.list_contacts` / `vmp.create_contact_group` | 联系组与联系人 |
|
|
32
|
+
| `vmp.list_notify_group_policies` | 取默认聚合策略 ID |
|
|
33
|
+
| `vmp.get_alerting_rule_template` / `vmp.list_alerting_rule_groups` | 写前读模板、写后回读 |
|
|
34
|
+
|
|
35
|
+
写协议:
|
|
36
|
+
|
|
37
|
+
1. 先 `alert templates` / `alert template` 确认模板 ID 与版本;不要自造 PromQL 或阈值。
|
|
38
|
+
2. 按模板 `Items` 生成参数,`Variables` 绑定 endpoint,`Tags` 打 `ark_endpoint_<id>`;`Items[].Enable` 显式传 `true`。
|
|
39
|
+
3. 执行前展示完整 `--params`、目标 workspace 和影响(新建 / 更新 / 删除),取得用户确认。
|
|
40
|
+
4. 执行 `arkcli api vmp.<action> --params '<json>'`。
|
|
41
|
+
5. 回读:`alert list` 核对规则组、启用状态与 tags;`arkcli api vmp.list_notify_policies` 核对通知绑定。
|
|
42
|
+
6. 只有回读通过才能说"已创建 / 已生效"。
|
|
43
|
+
|
|
44
|
+
示例(创建规则组):
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
arkcli api vmp.create_alerting_rule_group --params '{
|
|
48
|
+
"Name": "ark_alerting_rules_ep-a",
|
|
49
|
+
"WorkspaceId": "ws-xxx",
|
|
50
|
+
"AlertingRuleTemplateId": "b2876e3d-c52b-41d6-9b41-1b020fc7b2aa",
|
|
51
|
+
"AlertingRuleTemplateVersion": "<从 alert template 读回>",
|
|
52
|
+
"Items": [{"Id": 1, "Enable": true}],
|
|
53
|
+
"Variables": [{"Id": 1, "Values": ["ep-xxx"]}],
|
|
54
|
+
"Tags": [{"Key": "ark_endpoint_ep-xxx", "Value": "true"}]
|
|
55
|
+
}'
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## 边界
|
|
59
|
+
|
|
60
|
+
- 单次配置优先走控制台(表单、模板校验、影响预览更完整);CLI 面向批量与可重复编排。
|
|
61
|
+
- 通知实际投递无法通过 OpenAPI 验证;只能验证规则存在、启用状态与通知策略绑定。投递测试需在控制台或真实告警中完成。
|
|
62
|
+
- 不把 `watch` 当常驻告警;CLI 没有内建调度。定时巡检由宿主编排(见 `arkcli-vmp-workflows` 的 scheduler 参考)。
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# 能力模型(VMP × arkcli)
|
|
2
|
+
|
|
3
|
+
本页固定"什么由控制台做、什么由 CLI 做、什么两边都不做",用于回答"arkcli 能不能做 X"时避免越界承诺或重复建设。
|
|
4
|
+
|
|
5
|
+
## 四个维度
|
|
6
|
+
|
|
7
|
+
| 维度 | 取值 | 说明 |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| 对象 | 指标 / 告警 / 通知 / 工作区 / 追踪 / 日志 | VMP 域当前只覆盖指标、告警、通知、工作区 |
|
|
10
|
+
| 操作深度 | L0 渲染 / L1 查询 / L2 证据 / L3 判断 / L5 交付 / L4 写入 | 见下表 |
|
|
11
|
+
| 执行面 | 控制台 / CLI / 共享 OpenAPI | CLI 只是 OpenAPI 的一种调用方 |
|
|
12
|
+
| 产品 | 标品 VMP | 告警后端不同,不能互串 |
|
|
13
|
+
|
|
14
|
+
## 深度分工
|
|
15
|
+
|
|
16
|
+
| 深度 | 内容 | 归属 |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| L0 | 图表、仪表盘、告警规则表单、Trace 火焰图、日志检索 | 控制台。CLI 不做渲染 |
|
|
19
|
+
| L1 | 查询指标、列规则组、取模板、列通知策略 | 两边都做;CLI 输出结构化 JSON |
|
|
20
|
+
| L2 | 时间对齐、分片、覆盖率、峰值、逐 EP 证据、发布前后 diff、错误码聚合、TPM 利用率 | arkcli。控制台不产出可审计证据 |
|
|
21
|
+
| L3 | 判定口径与业务策略:阈值、发布放行、容量结论、异常处置 | arkcli 提供确定性原子判定(`compare` / `errors` / `capacity`);Skill 编排层负责阈值选择、例外解释和最终决策 |
|
|
22
|
+
| L4 | 建工作区、绑 telemetry、告警规则 CRUD、打标签 | 共享 OpenAPI。单次配置走控制台表单;批量 / 幂等编排走 CLI(先展示参数,写后回读) |
|
|
23
|
+
| L5 | 推飞书、写文档/看板、定时巡检 | Skill 编排层 + 宿主能力,不在 CLI 内建 |
|
|
24
|
+
|
|
25
|
+
## 产品分支
|
|
26
|
+
|
|
27
|
+
| 产品 | 指标后端 | 告警后端 | arkcli 现状 |
|
|
28
|
+
|---|---|---|---|
|
|
29
|
+
| 标品(CN) | VMP | VMP 告警(规则组 / 模板 / 通知策略) | 支持采集、查询、告警只读;告警写入走 `arkcli api vmp.*` 原始 action |
|
|
30
|
+
|
|
31
|
+
**判定规则**:先确认产品。只有标品 CN 的告警是 VMP 告警。
|
|
32
|
+
|
|
33
|
+
## 明确不做
|
|
34
|
+
|
|
35
|
+
- 不做仪表盘、Trace 检索、日志检索的渲染或替代。
|
|
36
|
+
- 不复制控制台的表单校验;单次告警配置优先引导控制台。
|
|
37
|
+
- 不验证通知实际投递(VMP OpenAPI 不暴露投递记录);只能验证规则存在、启用状态和通知策略绑定。
|
|
38
|
+
- 不在 CLI 内建常驻调度;定时由宿主(Skill 编排层)负责。
|
|
39
|
+
- 不做权限 / IAM 管理;跨服务授权只做检测与引导。
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# 十四天历史峰值与容量证据
|
|
2
|
+
|
|
3
|
+
解析范围、固定十四天 start/end,并保留一分钟 step/range。基础层分片查询和去重,不把十四天压成大窗口后取平均。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
arkcli doctor monitor capacity --endpoint ep-a,ep-b --start 2026-10-01T00:00:00Z --end 2026-10-15T00:00:00Z --step 1m --range 1m --format json
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
输出 `vmp.capacity.v1`,含逐 EP RPM、输入 TPM、输出 TPM、purchased completion TPM 的 collection evidence。峰值有时间戳,缺数据不会变成零,单位为 req/min 或 tokens/min。
|
|
10
|
+
|
|
11
|
+
`capacity` 会计算逐 EP 利用率:`peak_total_tpm = max(input TPM + output TPM)`(原始点可用时按时间戳对齐;不可用时退化为两侧峰值相加的上界),`purchased_tpm` 取 `token_type="completion"` 的最新观测,`utilization = peak_total_tpm / purchased_tpm`。`>=0.8` 为 `warning`,`>=1.0` 为 `critical`;配额缺失、覆盖不足或没有正 TPM 样本时 `inconclusive`。
|
|
12
|
+
|
|
13
|
+
`assumptions[]` 必须随报告保留:配额口径来自 completion 指标,若账号按其它口径计费,以控制台为准。可回答“观测到的历史峰值、何时出现、数据覆盖多少、逐 EP 利用率是多少”;不能仅凭该输出给出账单口径的配额余量或安全调额比例。不要将所有 EP 峰值求和称为项目同时峰值,也不要把 input TPM 单独除以 completion 配额。
|
|
14
|
+
|
|
15
|
+
需要看模型级免费额度余量时加 `--include-free-quota`:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
arkcli doctor monitor capacity --endpoint ep-a,ep-b --window 336h --step 1m --range 1m --include-free-quota --format json
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
输出新增 `free_quota`:`status`(available/partial/unavailable)、`matched_endpoints`、`unmatched_endpoints`,以及按模型聚合的 `balances[]`(`model`、`total`、`consumed`、`remaining`、`scope`);逐 EP 行也会带 `model` 和该模型的 `free_quota`。额度读取兼容 `InferenceFreeUsage` 与 `ResourcePackItems[Type=FreeInference]` 两种定价快照形态。口径是**模型级免费额度**(同模型的所有 EP 共享),不是单个 EP 独占余量;自定义模型 ID 没有对应的基础模型额度行时记为 unmatched。免费额度查询是 best-effort:pricing 或 EP 元数据失败时降级为 `free_quota.status=unavailable` 并保留容量结论,不会让整个命令失败。
|
|
22
|
+
|
|
23
|
+
若用户要安全调整配额,先读 当前安装的 `arkcli-quota` Skill(仅在当前产品提供该 Skill 时),按实际支持的配额池和 dry-run/plan 契约衔接;其它产品保留建议和所缺证据。建议需结合流量预测、余量策略、限流和明确可比的配额口径,不能用临时脚本绕开确认或计划校验。
|
|
24
|
+
|
|
25
|
+
产出:逐 EP 历史峰值及时间、coverage、缺片/空数据、配额证据、限制、建议补充的事实。TTFT 当前不可用;E2E 时延、吞吐量和配额是不同指标。
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# 可信采集与前后对比
|
|
2
|
+
|
|
3
|
+
`collect` 为明确 EP 集合返回 `vmp.collection.v1`。先解析用户资源,把示例 ID 替换为实际 ID。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
arkcli doctor monitor collect --endpoint ep-a,ep-b --window 30m --step 1m --range 1m --format json
|
|
7
|
+
arkcli doctor monitor collect --endpoint ep-a --start 2026-10-01T00:00:00Z --end 2026-10-15T00:00:00Z --step 1m --range 1m --summary-only --format json
|
|
8
|
+
arkcli doctor monitor collect --endpoint ep-a --metric request.rpm.by_api --metric request.duration.quantile --window 1h --range 5m --format json
|
|
9
|
+
arkcli doctor monitor collect --endpoint ep-a --metric request.rpm.by_api,request.tpm.input --window 1h --range 5m --format json
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
可用 catalog ID:`request.rpm.by_api`、`request.error.rate`、`request.duration.quantile`、`request.tpm.input`、`request.tpm.output`、`quota.purchased.tpm`。最后一项需显式选择。`snapshot` 返回相同契约的默认五项摘要。
|
|
13
|
+
|
|
14
|
+
## 隐式 Endpoint 范围
|
|
15
|
+
|
|
16
|
+
不想逐个列 ID 时,用 `--mine`、`--model`、`--name-regex`、`--status` 让 CLI 在控制面解析 EP 集合;四个条件可组合(AND),与 `--endpoint` 互斥:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
arkcli doctor monitor collect --mine --model doubao-seed-1.6 --status running --window 30m
|
|
20
|
+
arkcli doctor monitor snapshot --model doubao-seed-1.6 --name-regex '^prod-' --format json
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- 解析在命令开始时执行一次(watch 不会逐轮刷新),结果写入输出的 `scope`:`source`、`requested`、`resolved`、`resolved_at`;`resolved` 即本次实际查询的 EP 清单。
|
|
24
|
+
- `--mine` 优先使用服务端 `sys:ark:createdBy` 标签过滤;无法取得 ARK IAM UserID 的降级身份会退回客户端用户名后缀匹配,标签缺失或零匹配时直接报错,不会退化成全项目扫描。
|
|
25
|
+
- `--status` 接受 `Abnormal/Running/Scheduling/Stopped`,逗号分隔。
|
|
26
|
+
- 解析结果按 ID 排序;超过 50 个时截断,`scope.truncated=true`、`scope.skipped[]` 记录未纳入的 EP。匹配为零时报错,不静默查空。
|
|
27
|
+
- 范围一旦解析,报告里必须引用 `scope` 和时间;不要把它当作“项目全量”。
|
|
28
|
+
|
|
29
|
+
限制:1–50 个明确 EP ID,最大 744h,step 1s–1h,range 1m–1h,均需整秒;最多两百万个预期采样。多批保持相同 start/end。start/end 均向下对齐到 Unix epoch 的 step 网格(VMP 长跨度返回 epoch 对齐采样,短跨度沿用请求起点;统一网格避免丢点),实际范围以 window 为准。每片最多 360 个 step,边界重叠去重,不扩大统计窗口。PromQL 中固定保留 Endpoint 维度,直方图保留 le,TPM 已转成 tokens/min,RPM 按 range 归一化。
|
|
30
|
+
|
|
31
|
+
## 负载与安全
|
|
32
|
+
|
|
33
|
+
查询数按 `metric × 时间分片` 计算,EP 只在 PromQL 的 `endpoint=~"^(...)$"` 里聚合,所以 30 个 EP 和 1 个 EP 的查询数相同。执行前先看计划:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
arkcli doctor monitor collect --endpoint ep-a,ep-b --window 30m --plan
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`--plan` 只输出 `vmp.query_plan.v1`(queries、max_samples、estimated_seconds),不访问 VMP。默认 `--max-qps 2` 做客户端限速;429/5xx 按 1s、2s 有界退避,最多 3 次,其它错误立即失败。长跨度(例如 744h × 1m)会分成 56 片/指标,先用 `--plan` 估算,必要时降 step 或缩范围。不要把 `--max-qps` 当成绕过工作区配额的开关。
|
|
40
|
+
|
|
41
|
+
保存结果时可使用 shell 重定向到新的任务文件。不要覆盖之前的证据。输出字段:
|
|
42
|
+
|
|
43
|
+
- `workspace_id`、`endpoints`、`window`、`range`:实际查询范围。
|
|
44
|
+
- `results[]`:逐 EP、逐指标的 `unit`、`status`、`coverage`、`observed_points`、`expected_points`、`peak{ts,value}`、`latest`、`sample_mean`、可选 `points`。
|
|
45
|
+
- `queries[]`:每片实际 PromQL、时间、状态和错误。缺片返回 partial;所有查询失败会先输出证据再以非零退出。
|
|
46
|
+
- 空数据没有 peak/latest/sample_mean。`--summary-only` 只省略 points,保留证据和峰值时间。
|
|
47
|
+
|
|
48
|
+
前后对比:优先用 `arkcli doctor monitor compare`,它冻结两个等长、不重叠窗口,逐 EP 计算 `sample_mean`/峰值的 delta 与 `pass|violation|inconclusive` 判定;`--min-coverage`、`--max-error-rate-delta`、`--max-latency-delta-pct`、`--min-rpm-ratio` 随输出回显。为避免 range 回看跨越发布边界,发布后区间应从“发布时间 + range”开始。只有需要自定义规则(例如按 API 交叉、TPM 专项)时才用两次 `collect` 保存原始证据后在 Agent 侧计算。错误码分布用 `arkcli doctor monitor errors`,不要自己拼 `increase_pure`。不要把不同 EP 的 ratio 平均成项目错误率,也不要把一分钟峰值当作单请求值。缺数据的维度结论为不可判定。
|
|
49
|
+
|
|
50
|
+
报告至少包含:目标、profile 范围、EP 清单来源和解析时间、两个区间、step/range、指标单位、覆盖率、峰值时间、变化、原始证据路径、判断限制。
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Task acceptance scenarios
|
|
2
|
+
|
|
3
|
+
These are behavioral acceptance cases, not evidence of a live VMP run. CLI and collector regression tests use deterministic VMP fixtures.
|
|
4
|
+
|
|
5
|
+
| Prompt / fixture | Required behavior |
|
|
6
|
+
|---|---|
|
|
7
|
+
| Watch ep-a and ep-b for 30m; no thresholds supplied | Save baseline, use explicit IDs and bounded JSONL watch, check end, describe observations without inventing a pass threshold |
|
|
8
|
+
| Compare equal intervals around release T | Use `doctor monitor compare` with equal non-overlapping windows; verdict only from coverage-qualified deltas (`--min-coverage`, `--max-error-rate-delta`, `--max-latency-delta-pct`, `--min-rpm-ratio`); no causal language |
|
|
9
|
+
| Two weeks of ep-a traffic with a one-minute spike on day seven | Preserve 1m step/range, report 20161 grid points and exact spike time; never coarsen range to fourteen days; capacity reports per-EP utilization, not just a peak |
|
|
10
|
+
| Error spike: which codes and which EP | Use `doctor monitor errors`; hourly disjoint shards, per-EP error rate and top error codes; zero errors with traffic is `available` with empty codes; no traffic is `no_data` |
|
|
11
|
+
| One shard fails, another EP has no samples | Preserve query error, coverage and missing peak; partial/inconclusive rather than zero or healthy |
|
|
12
|
+
| Input 600 TPM, output 60 TPM, purchased completion quota 100 | No input/quota division; `doctor monitor capacity` reports utilization against purchased completion TPM and keeps unverified scope in `assumptions` |
|
|
13
|
+
| All samples have RPM zero and latency is missing | Describe observed zero traffic; no claim that rollout or latency validation passed |
|
|
14
|
+
| Watch cancelled or output lacks end | Report interruption/truncation and retain earlier evidence; no persistent-monitoring claim |
|
|
15
|
+
| List alerts / alert templates | Read real rule groups via `doctor monitor alert list`; template catalog and detail are read-only; no invented rule IDs |
|
|
16
|
+
| Create or update an alert | Only via explicit `arkcli api vmp.*` params after confirmation; read back with `alert list`; never claim delivery verification |
|
|
17
|
+
| All project endpoints in shared workspace | Resolve every inventory page first, exact IDs, same fixed bounds for batches; never query unrestricted workspace scope |
|
|
18
|
+
| User asks for TTFT | State unsupported verified metric; do not substitute E2E P99 |
|
|
19
|
+
|
|
20
|
+
Host evidence should record actual tool outputs, binary identity and fixture/live provenance. Live acceptance additionally needs a user-authorized endpoint set with a bound workspace and representative traffic; do not label fixture runs as production verification.
|
|
21
|
+
|
|
22
|
+
## Trigger and anti-trigger routing
|
|
23
|
+
|
|
24
|
+
- Trigger: "Watch ep-a and ep-b during rollout" uses baseline and bounded observation.
|
|
25
|
+
- Anti-trigger: "How many tokens did I use this month?" routes to arkcli-usage; a known endpoint failure routes to arkcli-doctor.
|
|
26
|
+
- Guard: expired credentials route to arkcli-auth. Missing workspace binding is reported without creating it. Identity inspection follows shared auth status/whoami behavior; no routine profile/key synchronization.
|
|
27
|
+
|
|
28
|
+
## CLI happy path
|
|
29
|
+
|
|
30
|
+
With an authorized fixture or live endpoint set and bound workspace:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
arkcli doctor monitor collect --endpoint ep-a,ep-b --window 5m --step 1m --range 1m --format json
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Assert explicit endpoint scope, one shared time range, per-result coverage and query provenance. A fixture with ep-a samples and no ep-b samples must preserve ep-a's observations and mark ep-b no_data with no peak value.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# 逐 Endpoint 快照
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
arkcli doctor monitor snapshot --endpoint ep-a,ep-b --window 5m --range 1m --format json
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
snapshot 是默认五个指标的 summary-only collection。它固定各查询的时间范围并保留每个 EP,输出含峰值时间、coverage 和 queries。阅读 [采集契约](collect.md),检查状态后再作判断。available 不是健康状态;无流量无法验证时延或错误率。
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# 明确范围内的峰值排行
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
arkcli doctor monitor top --endpoint ep-a,ep-b --metric rpm --limit 5 --window 1h --format json
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
metric 可选 rpm、error_rate、latency、tpm(input)、output_tpm;limit 1–50。返回 vmp.ranking.v1,order=observed_peak_desc,items 为先排序后截取的结果,evidence 保留全范围采集。相同峰值按 EP ID 稳定排序。空数据排后,无数值不会填零。
|
|
8
|
+
|
|
9
|
+
只按已解析的 EP 排名;不支持隐式全工作区、model/api 分组或把不同 EP 的峰值求和当成同时峰值。latency 是 E2E P99 观测点的峰值,并非窗口整体 P99。
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# 多 Endpoint 放量观察
|
|
2
|
+
|
|
3
|
+
1. 明确 EP 清单、观察时长和判据(例如用户给定的错误率或 E2E P99 上限)。没有判据时只报告变化,不擅自判定通过。
|
|
4
|
+
2. 用 snapshot/collect 保存放量前基线。需要严格对比时固定 start/end。说明基线流量、覆盖率和统计窗口。
|
|
5
|
+
3. 启动有界观察,立即首轮,之后每轮完成后等待 interval;duration 限制整个会话,window 不随 interval 改变。
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
arkcli doctor monitor snapshot --endpoint ep-a,ep-b --window 10m --range 1m --format json
|
|
9
|
+
arkcli doctor monitor watch --endpoint ep-a,ep-b --window 5m --range 1m --step 15s --interval 30s --duration 30m --summary-only --format jsonl
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
EP 清单也可以用 `--mine/--model/--name-regex/--status` 隐式解析,语义与 [采集契约](collect.md) 一致;范围只在启动时解析一次,watch 运行中不刷新。
|
|
13
|
+
|
|
14
|
+
## 阈值告警
|
|
15
|
+
|
|
16
|
+
`--alert-on` 在每轮采样后做确定性阈值判断,输出事件而非轮询全量日志:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
arkcli doctor monitor watch --endpoint ep-a,ep-b --window 5m --range 1m --interval 30s --duration 30m --alert-on 'error_rate>0.05,latency>2.5' --alert-for 3 --format jsonl
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
- 规则格式 `metric<op>threshold`,逗号分隔;op 支持 `>` `>=` `<` `<=` `==`。
|
|
23
|
+
- metric 别名:`rpm`、`error_rate`、`latency`、`tpm`、`output_tpm`、`coverage`。`coverage` 读证据覆盖率;带 `_delta` 后缀(如 `rpm_delta<-100`)时与上一轮采样比较,首轮跳过。
|
|
24
|
+
- `--alert-for N`(1–60,默认 1)要求连续 N 轮超阈值才触发,避免单点抖动。
|
|
25
|
+
- 事件 `type=alert`(state=firing/resolved)只在状态切换时输出一次;`type=sample` 仍照常输出。end 记录的 `active_alerts` 是结束时未恢复的告警数。
|
|
26
|
+
- 观察结束仍有未恢复告警时进程以非零退出,便于编排层判定;`resolved` 后正常结束则退出码为 0。
|
|
27
|
+
- 告警判断基于每轮已采集的证据,不额外发查询;阈值未命中不代表服务健康,仍需按判据检查 coverage 和流量。
|
|
28
|
+
|
|
29
|
+
将输出保存为 `observation.jsonl`。每行 `vmp.watch.v1`,type=sample 包含 sequence/status/collection;type=end 表明 completed/cancelled/failed。completed 仅表示观察时间已结束,不是健康通过。取消时仍有 end,先前样本已保留,进程返回取消错误;未完成的当前查询不当作完整样本。若写文件/输出失败,终止记录也可能缺失,此时报告截断证据。
|
|
30
|
+
|
|
31
|
+
4. 根据用户判据逐 EP 检查样本。发现异常时记录时间、指标、阈值、覆盖率和对应查询,按 arkcli-doctor 的现有能力诊断该 EP。不要拿低覆盖率或零流量当作通过。刷新间隔和统计窗口重叠,所以相邻样本并非独立事件。
|
|
32
|
+
5. 报告基线、观察区间、是否完整结束、异常样本、诊断结果、未判定项和建议。没有 end、发生取消、数据缺失或无有效流量时说明限制;不宣称“已经持续监控”或“告警已生效”。
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: arkcli-vmp-workflows
|
|
3
|
+
version: 1.0.0
|
|
4
|
+
description: 编排 ARK 可观测工作流:放量盯盘、发布前后对比、容量复盘、每日巡检和异常下钻。用户说“盯放量并推飞书”“每天巡检发日报”“发布前后对比出报告”“异常了帮我下钻”时使用。组合 arkcli-vmp 的证据与飞书/看板/宿主调度;采集保持只读,告警写入是显式写操作(确认 + 回读),推送、定时和留档由本 Skill 执行。
|
|
5
|
+
metadata:
|
|
6
|
+
requires:
|
|
7
|
+
bins: ["arkcli"]
|
|
8
|
+
cliHelp: "arkcli doctor monitor --help"
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# ARK 可观测工作流编排
|
|
12
|
+
|
|
13
|
+
**CRITICAL — 开始前 MUST 先读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) 与 [`../arkcli-vmp/SKILL.md`](../arkcli-vmp/SKILL.md)。** 前者是认证与安全协议,后者是能力面命令契约和证据解释。本 Skill 只负责编排、判定、推送、留档和完成判据,不重算指标。
|
|
14
|
+
|
|
15
|
+
## 这一层解决什么
|
|
16
|
+
|
|
17
|
+
能力面回答“数据是什么”;编排面回答“这个任务现在算完成了吗、下一步做什么、结果发给谁”。同一个能力面证据可以被多个工作流复用;工作流不固化成 CLI 命令,阈值、接收方、节奏和分支在 Skill/宿主侧调整。
|
|
18
|
+
|
|
19
|
+
## 工作流路由
|
|
20
|
+
|
|
21
|
+
| 用户目标 | 工作流 | 参考 |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| 放量/压测期间盯住一组 EP,按阈值判断并推送 | vmp-rollout-watch | [放量盯盘](references/rollout-watch.md) |
|
|
24
|
+
| 发布前后是否退化,生成对比报告 | vmp-release-compare | [发布对比](references/release-compare.md) |
|
|
25
|
+
| 过去两周峰值、覆盖率、容量证据 | vmp-capacity-review | [容量复盘](references/capacity-review.md) |
|
|
26
|
+
| 每天定时巡检并发日报 | vmp-daily-digest | [每日巡检](references/daily-digest.md) |
|
|
27
|
+
| 已发现异常,继续定位到 EP/错误/时延 | vmp-incident-drilldown | [异常下钻](references/incident-drilldown.md) |
|
|
28
|
+
| 想配置告警或飞书通知 | vmp-alert-provision | [告警开通](references/alert-provision.md) |
|
|
29
|
+
|
|
30
|
+
只查一次指标、快照或排行,用 `arkcli-vmp`;已有明确故障、只做诊断,用 `arkcli-doctor`。不要为了走工作流而重复采集。
|
|
31
|
+
|
|
32
|
+
## 产品路由(开始前必须确认)
|
|
33
|
+
|
|
34
|
+
先确认 profile 对应的产品,再选择告警路径。盯盘、发布对比、容量复盘、每日巡检和异常下钻的指标证据都走 `arkcli doctor monitor`(各产品指标后端一致);告警后端不同,不能互串。
|
|
35
|
+
|
|
36
|
+
| 产品 | 告警后端 | 告警路径 |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| 标品 CN | VMP 告警 | `arkcli doctor monitor alert` 只读 + `arkcli api vmp.*` 写入,见 [告警开通](references/alert-provision.md) |
|
|
39
|
+
|
|
40
|
+
无法确认产品时先问用户,不要默认按标品 VMP 写告警。
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
## 统一执行协议
|
|
44
|
+
|
|
45
|
+
每个工作流按同一顺序执行:
|
|
46
|
+
|
|
47
|
+
1. **确定任务与判据。** 明确产品、EP 集合、时间范围、指标、阈值、接收方和授权范围。用户没给阈值时只做描述性观察,不宣布通过。
|
|
48
|
+
2. **解析范围。** 用户给 EP 时直接使用;说“全项目”时先按 `arkcli-vmp` 的清单流程读取控制面全部分页,保存清单来源与解析时间。单批 1–50 个 EP,多批共享同一 start/end。
|
|
49
|
+
3. **冻结参数。** 固定 profile、产品、window/start/end、step、range、interval、duration、指标和单位。工作流运行中不改口径;要改就新开 run。
|
|
50
|
+
4. **采集并保存证据。** 原始 JSON/JSONL 写入本次 run 的 `evidence/`,不要覆盖历史文件。检查 collection.status、逐 EP status/coverage 和 queries。
|
|
51
|
+
5. **判定。** 只用能力面输出计算;结论分为 `pass` / `violation` / `inconclusive`。`partial`、`no_data`、低覆盖率和真实零流量都不能写成健康。
|
|
52
|
+
6. **执行副作用。** 推送、写文档、写 Base/Sheet 前必须展示目标、内容摘要和接收方;用户确认后执行。副作用要幂等并回读。
|
|
53
|
+
7. **留档并报告。** 写 `run.json` 和 `report.md`,报告包含目标、范围、证据路径、判定、限制、副作用回读结果和下一步。
|
|
54
|
+
|
|
55
|
+
## 运行记录与副作用契约
|
|
56
|
+
|
|
57
|
+
每个 run 使用独立目录:
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
runs/<workflow>/<run-id>/
|
|
61
|
+
run.json # arkcli.workflow.run.v1
|
|
62
|
+
report.md # 人读报告
|
|
63
|
+
evidence/ # 原始 JSON/JSONL
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`run.json` 的最小字段见 [运行记录](references/run-record.md)。副作用统一走适配器:
|
|
67
|
+
|
|
68
|
+
- `notify`:发飞书消息/卡片;参数为 channel、target、title、summary、evidence links、idempotency key。
|
|
69
|
+
- `document`:创建或更新飞书文档;回读 document token。
|
|
70
|
+
- `table`:写入多维表格/电子表格;回读 record id 或 range。
|
|
71
|
+
- `schedule`:注册宿主定时任务;回读 job id、时区和下次运行时间。
|
|
72
|
+
|
|
73
|
+
飞书适配器见 [飞书集成](references/feishu.md);宿主调度见 [定时执行](references/scheduler.md)。没有对应工具或权限时,输出可复制的消息/文档草稿,并明确“尚未发送”。
|
|
74
|
+
|
|
75
|
+
## 完成判据
|
|
76
|
+
|
|
77
|
+
一个工作流只有同时满足以下条件才算完成:
|
|
78
|
+
|
|
79
|
+
- 范围和口径已冻结,EP 清单可追溯;
|
|
80
|
+
- 证据文件存在,查询失败和缺口已解释;
|
|
81
|
+
- 判定与证据一致,不可判定时给出原因;
|
|
82
|
+
- 副作用已回读,或明确标记为未执行;
|
|
83
|
+
- `run.json` 的 status 与报告一致。
|
|
84
|
+
|
|
85
|
+
## 反唤起
|
|
86
|
+
|
|
87
|
+
- 单纯查用量/账单:`arkcli-usage` / `arkcli-billing`。
|
|
88
|
+
- 已有明确错误码或 EP 故障:`arkcli-doctor`。
|
|
89
|
+
- 只做一次采集/快照/排行:`arkcli-vmp`。
|
|
90
|
+
- 创建/更新 Endpoint、配额、模型:对应能力 Skill;本 Skill 不执行这些写操作。
|
|
91
|
+
- 告警写入:单次配置优先引导控制台;批量 / 幂等编排才走 `arkcli api vmp.*`,且必须确认参数、写后回读。投递验证与调度仍由控制台 / 宿主负责。
|
|
92
|
+
|
|
93
|
+
## 能力边界
|
|
94
|
+
|
|
95
|
+
- 本 Skill 不新增 CLI 命令。采集与告警读取只读;告警写入是显式写操作,只通过 `arkcli api vmp.*` 原始 action 提供,必须"先展示参数、再执行、后回读"。
|
|
96
|
+
- 告警能力只覆盖标品 CN 的 VMP 告警;其他产品或环境的告警后端不同,不要用 VMP 告警 API 代替,遇到时说明边界并给出对应控制台路径。
|
|
97
|
+
- 定时执行依赖宿主,不是 CLI 内建调度;进程退出后 watch 不会继续。
|
|
98
|
+
- 飞书集成需要机器人和目标群/文档权限;没有权限时保留本地报告。
|
|
99
|
+
- 通知实际投递无法通过 OpenAPI 验证;只能验证规则存在、启用状态与通知策略绑定。投递测试需在控制台或真实告警中完成。
|
|
100
|
+
- 本 Skill 面向国内站与飞书;TT 等其他产品形态暂不随包分发。
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# 告警开通(vmp-alert-provision)
|
|
2
|
+
|
|
3
|
+
本工作流按产品分两条告警路径,开始前先确认产品。指标证据仍来自 `arkcli doctor monitor`;告警后端不同,不能互串。
|
|
4
|
+
|
|
5
|
+
## 标品 CN:VMP 告警
|
|
6
|
+
|
|
7
|
+
适用范围:**标品 CN 的 VMP 告警**。
|
|
8
|
+
|
|
9
|
+
命令契约与写协议见 [`../../arkcli-vmp/references/alert.md`](../../arkcli-vmp/references/alert.md);能力分工见 [`../../arkcli-vmp/references/capability-model.md`](../../arkcli-vmp/references/capability-model.md)。
|
|
10
|
+
|
|
11
|
+
### 能力现状
|
|
12
|
+
|
|
13
|
+
- 只读:`arkcli doctor monitor alert list` / `alert templates` / `alert template --template-id` 可用。
|
|
14
|
+
- 写入:`arkcli api vmp.create_alerting_rule_group` / `update_alerting_rule_group` / `delete_alerting_rule_group`、`tag_resources` / `untag_resources`、通知策略与联系组 action 可用,但**没有 shortcut**。
|
|
15
|
+
- 仍不可验证:通知实际投递(OpenAPI 不暴露投递记录);CLI 没有内建调度。
|
|
16
|
+
- 单次配置优先引导控制台;批量 / 幂等编排才走 CLI。
|
|
17
|
+
|
|
18
|
+
### 开通规格
|
|
19
|
+
|
|
20
|
+
执行前先把规格填完整,缺项标为待确认,不要自造 PromQL 或阈值:
|
|
21
|
+
|
|
22
|
+
| 字段 | 内容 |
|
|
23
|
+
|---|---|
|
|
24
|
+
| 范围 | profile、产品(必须是标品 CN)、workspace、EP 集合 |
|
|
25
|
+
| 指标 | 模板 ID / 版本、指标 ID、单位、统计窗口 |
|
|
26
|
+
| 阈值 | 触发值、比较方向、持续时间(模板默认值可覆盖时写明) |
|
|
27
|
+
| 缺数据策略 | 缺数据是否触发、连续多久 |
|
|
28
|
+
| 恢复条件 | 恢复阈值与持续时间 |
|
|
29
|
+
| 通知 | 接收人/群、通知渠道、通知策略、联系组 |
|
|
30
|
+
| 标签 | `ark_endpoint_<id>`(控制台按标签反查) |
|
|
31
|
+
| 验证 | 规则回读、启用状态、通知绑定;投递测试注明由控制台完成 |
|
|
32
|
+
|
|
33
|
+
### 执行
|
|
34
|
+
|
|
35
|
+
1. 确认产品与 workspace;未绑定时先解决 telemetry 绑定,不要直接写告警。
|
|
36
|
+
2. `arkcli doctor monitor alert templates` 选模板,`alert template --template-id` 读回版本、PromQL 与默认阈值。
|
|
37
|
+
3. 生成 `vmp.create_alerting_rule_group` 参数:`Items[].Enable=true`,`Variables` 绑定 endpoint,`Tags` 打 `ark_endpoint_<id>`。
|
|
38
|
+
4. 需要通知时:`vmp.list_notify_policies` 查现有策略,必要时 `vmp.create_contact_group` + `vmp.create_notify_policy`(Levels 按 P0/P1/P2 升序)。
|
|
39
|
+
5. 展示完整 `--params`、目标 workspace 和影响;用户确认后执行。
|
|
40
|
+
6. 回读:`alert list` 核对规则组、启用状态、tags;`vmp.list_notify_policies` 核对绑定。
|
|
41
|
+
7. 把规格、命令、回读证据写入 `run.json` 与 `report.md`。
|
|
42
|
+
|
|
43
|
+
### 判定
|
|
44
|
+
|
|
45
|
+
- `planned`:规格完整,但未执行写入。
|
|
46
|
+
- `created`:写入成功且 `alert list` 回读到规则组。
|
|
47
|
+
- `verified`:规则、启用状态、通知绑定三项都有回读证据。**投递验证不在 CLI 判定范围内**,报告里单列为"待控制台/真实告警验证"。
|
|
48
|
+
- 任何一项缺失,不得升级为 `verified`。
|
|
49
|
+
|
|
50
|
+
### 批量编排示例
|
|
51
|
+
|
|
52
|
+
先 `alert list` 按 `ark_endpoint_<id>` 标签查重:已存在则走 `update_alerting_rule_group`,不要重复创建。确认参数后逐 EP 执行:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
for ep in ep-a ep-b; do
|
|
56
|
+
arkcli api vmp.create_alerting_rule_group --params "$(jq -n \
|
|
57
|
+
--arg ep "$ep" --arg ws "$WS" --arg tpl "$TPL" --arg ver "$VER" '{
|
|
58
|
+
Name: ("ark_alerting_rules_" + $ep),
|
|
59
|
+
WorkspaceId: $ws,
|
|
60
|
+
AlertingRuleTemplateId: $tpl,
|
|
61
|
+
AlertingRuleTemplateVersion: $ver,
|
|
62
|
+
Items: [{Id: 1, Enable: true}],
|
|
63
|
+
Variables: [{Id: 1, Values: [$ep]}],
|
|
64
|
+
Tags: [{Key: ("ark_endpoint_" + $ep), Value: "true"}]
|
|
65
|
+
}')"
|
|
66
|
+
done
|
|
67
|
+
arkcli doctor monitor alert list --workspace-id "$WS" --format json > evidence/alerts-after.json
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
批量脚本不是天然幂等:每轮执行前查重,执行后回读;任何一步失败都停止并报告已创建/已更新的范围。
|
|
71
|
+
|
|
72
|
+
### 示例提示词
|
|
73
|
+
|
|
74
|
+
“给 ep-a、ep-b 配一个错误率超过 5% 持续 5 分钟就飞书通知我的告警。”
|
|
75
|
+
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# 容量复盘(vmp-capacity-review)
|
|
2
|
+
|
|
3
|
+
## 何时使用
|
|
4
|
+
|
|
5
|
+
用户要看过去十四天的分钟级峰值、覆盖率,或为模型切换/扩缩容准备容量证据。
|
|
6
|
+
|
|
7
|
+
## 必填输入
|
|
8
|
+
|
|
9
|
+
- EP 集合。
|
|
10
|
+
- 截止时间(固定 end)。
|
|
11
|
+
- 配额来源与口径(已购 completion TPM 等)。
|
|
12
|
+
- 是否需要与七天窗口做同口径对照。
|
|
13
|
+
|
|
14
|
+
## 执行
|
|
15
|
+
|
|
16
|
+
1. 读 [capacity](../../arkcli-vmp/references/capacity.md) 与 [collect](../../arkcli-vmp/references/collect.md)。
|
|
17
|
+
2. 固定十四天 `start/end`,保持 `--step 1m --range 1m`;十四天写作 `336h`,不要写成 `14d`。
|
|
18
|
+
3. 采集:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
arkcli doctor monitor capacity --endpoint ep-a,ep-b --start 2026-10-01T00:00:00Z --end 2026-10-15T00:00:00Z --step 1m --range 1m --format json > evidence/capacity.json
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
4. 检查分片、coverage、缺片和空数据;十四天一分钟网格应为 20161 个点。两百万预期采样的上限意味着 14d/1m × 4 指标约支持 24 个 EP/批;更多 EP 分批,所有批次共享同一 start/end。不得为绕过限制扩大 range 或粗化 step。
|
|
25
|
+
5. 读取 `vmp.capacity.v1`:
|
|
26
|
+
- `endpoints[].peak_input_tpm`、`peak_output_tpm`、`peak_total_tpm`(优先时间对齐求和,无法对齐时是上界)。
|
|
27
|
+
- `purchased_tpm` 来自 `ark_api_proxy_purchased_provisioned_tpm{token_type="completion"}` 的最新观测。
|
|
28
|
+
- `utilization = peak_total_tpm / purchased_tpm`;`>=0.8` 为 warning,`>=1.0` 为 critical。
|
|
29
|
+
- `inconclusive` 表示配额缺失、覆盖不足或没有正 TPM 样本,不是健康。
|
|
30
|
+
6. 不同 EP 的峰值不能相加为项目同时峰值;需要项目同时峰值时,按同一时间戳聚合后单独计算。
|
|
31
|
+
7. 需要七天对照时,用同一 EP 集、同一 step/range、同一截止时间重新采集,不引用不同口径的历史结论。
|
|
32
|
+
8. 配额口径仍以控制台为准:`capacity` 的假设已写在 `assumptions[]`,报告必须原样保留;不要把 `utilization` 直接当成账单或安全调额比例。
|
|
33
|
+
|
|
34
|
+
## 判定
|
|
35
|
+
|
|
36
|
+
- 能回答:观测到的历史峰值、峰值时间、覆盖率、逐 EP 利用率,以及 `ok/warning/critical` 判定。
|
|
37
|
+
- 不能回答:账单口径的配额余量、项目同时峰值、TTFT、安全调额比例。
|
|
38
|
+
- 七天与十四天峰值不一致时,先确认同口径;CLI 不解释后端平滑或打点差异,把差异作为待核实事实。
|
|
39
|
+
|
|
40
|
+
## 报告模板
|
|
41
|
+
|
|
42
|
+
- 目标、EP 清单、截止时间
|
|
43
|
+
- 十四天区间、step/range、20161 点
|
|
44
|
+
- 逐 EP 峰值、峰值时间、coverage、缺片
|
|
45
|
+
- 逐 EP `purchased_tpm`、`peak_total_tpm`、`utilization`、`status` 与 reason
|
|
46
|
+
- 七天对照(同口径)
|
|
47
|
+
- `assumptions[]` 与待控制台核实的配额口径
|
|
48
|
+
- 证据路径与下一步核实项
|
|
49
|
+
|
|
50
|
+
## 失败处理
|
|
51
|
+
|
|
52
|
+
- 分片失败或 coverage 不足:保留已取得证据,标 `partial`,不宣布峰值。
|
|
53
|
+
- 配额缺失或口径不可比:`inconclusive`,列出缺的证据。
|
|
54
|
+
- 用户要求直接改配额:转 `arkcli-quota`(若当前产品提供),本 Skill 不执行写操作。
|
|
55
|
+
|
|
56
|
+
## 示例提示词
|
|
57
|
+
|
|
58
|
+
“看 ep-a、ep-b 最近十四天的一分钟峰值和覆盖率,判断容量够不够;不够的话给出还缺什么证据。”
|