@volcengine/ark-cli-linux-x64 1.0.49-prerelease.8878038408e0 → 1.0.49
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 +44 -16
- package/package.json +1 -1
- package/skills/arkcli-helper/SKILL.md +2 -0
- package/skills/arkcli-helper/references/evals.md +1 -0
- 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
package/bin/arkcli-linux-amd64
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/bin/arkcli-linux-amd64
|
|
3
|
-
size:
|
|
4
|
-
sha256:
|
|
3
|
+
size: 40800418 bytes
|
|
4
|
+
sha256: 7b8c4ad9c8a2371e63ec4e0aaf0d6972c6fb4d3fc793b20c685261eca657fb36
|
package/manifest.json
CHANGED
|
@@ -1,37 +1,65 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "1.0.49
|
|
2
|
+
"version": "1.0.49",
|
|
3
3
|
"platforms": {
|
|
4
4
|
"darwin-amd64": {
|
|
5
|
-
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/
|
|
6
|
-
"sha256": "
|
|
5
|
+
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prod/1.0.49/arkcli-1.0.49-darwin-amd64",
|
|
6
|
+
"sha256": "99ee991b96dae9cdf48062a15c5de6ab562d0433fabc201048bc2ade02b3261e",
|
|
7
|
+
"fallback": {
|
|
8
|
+
"url": "https://github.com/volcengine/ark-cli/releases/download/v1.0.49/arkcli-1.0.49-darwin-amd64",
|
|
9
|
+
"kind": "github-release"
|
|
10
|
+
}
|
|
7
11
|
},
|
|
8
12
|
"darwin-arm64": {
|
|
9
|
-
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/
|
|
10
|
-
"sha256": "
|
|
13
|
+
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prod/1.0.49/arkcli-1.0.49-darwin-arm64",
|
|
14
|
+
"sha256": "0e27e58df9fecc7f479391d40f9a964e182b8a4472e43c78f3c7dbb22fd147b7",
|
|
15
|
+
"fallback": {
|
|
16
|
+
"url": "https://github.com/volcengine/ark-cli/releases/download/v1.0.49/arkcli-1.0.49-darwin-arm64",
|
|
17
|
+
"kind": "github-release"
|
|
18
|
+
}
|
|
11
19
|
},
|
|
12
20
|
"linux-amd64": {
|
|
13
|
-
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/
|
|
14
|
-
"sha256": "
|
|
21
|
+
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prod/1.0.49/arkcli-1.0.49-linux-amd64",
|
|
22
|
+
"sha256": "7b8c4ad9c8a2371e63ec4e0aaf0d6972c6fb4d3fc793b20c685261eca657fb36",
|
|
23
|
+
"fallback": {
|
|
24
|
+
"url": "https://github.com/volcengine/ark-cli/releases/download/v1.0.49/arkcli-1.0.49-linux-amd64",
|
|
25
|
+
"kind": "github-release"
|
|
26
|
+
}
|
|
15
27
|
},
|
|
16
28
|
"linux-arm64": {
|
|
17
|
-
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/
|
|
18
|
-
"sha256": "
|
|
29
|
+
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prod/1.0.49/arkcli-1.0.49-linux-arm64",
|
|
30
|
+
"sha256": "2269d377a3b510258ecbe6aeadc61fdd9830d71228bf51c742431340eb5f8a52",
|
|
31
|
+
"fallback": {
|
|
32
|
+
"url": "https://github.com/volcengine/ark-cli/releases/download/v1.0.49/arkcli-1.0.49-linux-arm64",
|
|
33
|
+
"kind": "github-release"
|
|
34
|
+
}
|
|
19
35
|
},
|
|
20
36
|
"windows-amd64": {
|
|
21
|
-
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/
|
|
22
|
-
"sha256": "
|
|
37
|
+
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prod/1.0.49/arkcli-1.0.49-windows-amd64.exe",
|
|
38
|
+
"sha256": "5ba49e8e35270a5d1358be4485a5fbf3cf26baf4f40678c8b5f49d6582d63e31",
|
|
39
|
+
"fallback": {
|
|
40
|
+
"url": "https://github.com/volcengine/ark-cli/releases/download/v1.0.49/arkcli-1.0.49-windows-amd64.exe",
|
|
41
|
+
"kind": "github-release"
|
|
42
|
+
}
|
|
23
43
|
},
|
|
24
44
|
"windows-arm64": {
|
|
25
|
-
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/
|
|
26
|
-
"sha256": "
|
|
45
|
+
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prod/1.0.49/arkcli-1.0.49-windows-arm64.exe",
|
|
46
|
+
"sha256": "1a4c0d103405535485dc62a12f620d5bbacf011b09e048baa9ba231384320c29",
|
|
47
|
+
"fallback": {
|
|
48
|
+
"url": "https://github.com/volcengine/ark-cli/releases/download/v1.0.49/arkcli-1.0.49-windows-arm64.exe",
|
|
49
|
+
"kind": "github-release"
|
|
50
|
+
}
|
|
27
51
|
}
|
|
28
52
|
},
|
|
29
53
|
"skills": {
|
|
30
54
|
"primary": {
|
|
31
|
-
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/
|
|
32
|
-
"sha256": "
|
|
55
|
+
"url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prod/1.0.49/skills.tar.gz",
|
|
56
|
+
"sha256": "62472b7a8255211273eeb357aa3b5033e160bb4eae29ba1d8f7ae66f08a007c3",
|
|
33
57
|
"kind": "cdn"
|
|
34
58
|
},
|
|
35
|
-
"tag": "v1.0.49
|
|
59
|
+
"tag": "v1.0.49",
|
|
60
|
+
"fallback": {
|
|
61
|
+
"url": "https://github.com/volcengine/ark-cli/archive/refs/tags/v1.0.49.tar.gz",
|
|
62
|
+
"kind": "github"
|
|
63
|
+
}
|
|
36
64
|
}
|
|
37
65
|
}
|
package/package.json
CHANGED
|
@@ -18,6 +18,8 @@ metadata:
|
|
|
18
18
|
组合,也不得把它当作写操作保护。真实 `configure/reset/mcp/supabase`
|
|
19
19
|
仍必须先展示目标与路径并取得明确确认。
|
|
20
20
|
|
|
21
|
+
真人每次启动 `arkcli helper` 时,向导会在选择 profile 前在线查询当前账号的 Agent Plan、Coding Plan 个人订阅和团队席位。新检测到的套餐会自动补建本地 profile,当次即可选择。套餐到期、回收或席位撤销时,向导显示原因并跳过该选项,保留本地 profile。续费或重新获得席位后即可再选原 profile。服务端未能确认状态时,条目标记为「状态待确认」,选用时再查询。
|
|
22
|
+
|
|
21
23
|
## 命令选择(先选最具体的子命令)
|
|
22
24
|
|
|
23
25
|
- 普通 Helper 准入从 `arkcli helper list` 和用户指定的目标开始;不要为补齐上下文自动执行 `profile show/list/keys list`。这些 Profile 命令可能在线同步并回写 Key,只有用户显式要求 Profile 管理时才进入,并先说明影响。
|
|
@@ -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。
|
|
@@ -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 最近十四天的一分钟峰值和覆盖率,判断容量够不够;不够的话给出还缺什么证据。”
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# 每日巡检(vmp-daily-digest)
|
|
2
|
+
|
|
3
|
+
## 何时使用
|
|
4
|
+
|
|
5
|
+
用户要每天固定时间巡检一组 EP 或整个项目,生成摘要并推送到飞书。
|
|
6
|
+
|
|
7
|
+
## 必填输入
|
|
8
|
+
|
|
9
|
+
- profile、产品、项目范围或明确 EP 集合。
|
|
10
|
+
- 回看窗口(例如过去 24h)、指标、异常阈值。
|
|
11
|
+
- 推送时间、时区、接收方(群/个人/文档/Base)。
|
|
12
|
+
- 失败时的接收人。
|
|
13
|
+
|
|
14
|
+
## 执行
|
|
15
|
+
|
|
16
|
+
1. 解析 EP 清单:用户给 EP 时直接用;说“全项目”时按 `arkcli-vmp` 的清单流程读取控制面全部分页,保存来源与解析时间。
|
|
17
|
+
2. 按批采集,所有批次共享同一 start/end:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
arkcli doctor monitor snapshot --endpoint ep-a,ep-b --window 24h --range 1m --format json > evidence/snapshot.json
|
|
21
|
+
arkcli doctor monitor top --endpoint ep-a,ep-b --metric error_rate --limit 10 --window 24h --format json > evidence/top-error.json
|
|
22
|
+
arkcli doctor monitor errors --endpoint ep-a,ep-b --window 24h --top-codes 5 --format json > evidence/errors.json
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- `snapshot` 给出逐 EP 的默认五项摘要(RPM、错误率、P99、输入/输出 TPM)。
|
|
26
|
+
- `top` 用于快速定位异常 EP。
|
|
27
|
+
- `errors` 给出逐 EP 错误码 Top N、错误率与规则化排查建议;错误率为零时 `codes` 为空、`status=available`,不是缺数据。
|
|
28
|
+
3. 需要 TPM 容量判断时追加:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
arkcli doctor monitor capacity --endpoint ep-a,ep-b --window 24h --step 1m --range 1m --format json > evidence/capacity.json
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`capacity` 的 `status` 为 `ok|warning|critical|inconclusive`;`inconclusive` 只表示配额或覆盖不足,不表示健康。
|
|
35
|
+
4. 按阈值筛选异常:错误率、E2E P99、TPM 利用率、零流量、coverage 不足。`available` 不是健康;零流量不能算通过。
|
|
36
|
+
5. 生成摘要:总览、异常 EP 列表、每项的时间/指标/值/阈值/证据、数据缺口、需要人工确认的项。
|
|
37
|
+
6. 推送:按 [飞书集成](feishu.md) 发 IM 或写文档/Base。幂等键使用 `date + profile + workflow`,发送后保存 message ID / document token 并回读。
|
|
38
|
+
7. 写 `run.json` 和 `report.md`;失败时保留本地证据并通知失败接收人。
|
|
39
|
+
|
|
40
|
+
## 最小可执行编排
|
|
41
|
+
|
|
42
|
+
宿主包装脚本只做“调用 CLI + 汇总 + 推送”,不复制采集逻辑:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
#!/usr/bin/env bash
|
|
46
|
+
set -euo pipefail
|
|
47
|
+
run_id="$(date +%Y%m%dT%H%M%S)-$(openssl rand -hex 3)"
|
|
48
|
+
dir="runs/vmp-daily/$run_id"; mkdir -p "$dir/evidence"
|
|
49
|
+
date_key="$(date +%F)"
|
|
50
|
+
# 1) 证据:失败时保留已取得的 JSON,不覆盖历史
|
|
51
|
+
arkcli doctor monitor snapshot --endpoint "$EPS" --window 24h --range 1m --format json > "$dir/evidence/snapshot.json"
|
|
52
|
+
arkcli doctor monitor errors --endpoint "$EPS" --window 24h --top-codes 5 --format json > "$dir/evidence/errors.json"
|
|
53
|
+
# 2) 报告:由 Agent 或 jq 生成 $dir/report.md,写入判定、异常项、coverage 和证据路径
|
|
54
|
+
# 3) 推送:幂等键在 1 小时内去重;发送后保存返回的 message_id
|
|
55
|
+
lark-cli im +messages-send --chat-id "$CHAT_ID" --markdown @"$dir/report.md" \
|
|
56
|
+
--idempotency-key "vmp-daily-$date_key"
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
发送前必须向用户展示目标群、标题、摘要和证据链接;没有 `lark-cli` 时只保留 `report.md` 并标记“尚未发送”。
|
|
60
|
+
|
|
61
|
+
## 调度
|
|
62
|
+
|
|
63
|
+
本 Skill 不内建调度器。按 [定时执行](scheduler.md) 在宿主注册任务;任务只调用本工作流,不复制采集逻辑。
|
|
64
|
+
|
|
65
|
+
## 判定
|
|
66
|
+
|
|
67
|
+
- `pass`:范围内 EP 均有足够覆盖,且没有超过阈值的异常。
|
|
68
|
+
- `violation`:存在超过阈值的异常 EP。
|
|
69
|
+
- `inconclusive`:清单解析失败、覆盖不足、查询失败或阈值不明确。
|
|
70
|
+
- 发送失败不等于巡检失败:数据结论可以成立,但必须标 `side_effect_failed`。
|
|
71
|
+
|
|
72
|
+
## 报告模板
|
|
73
|
+
|
|
74
|
+
- 日期、profile、范围、解析时间
|
|
75
|
+
- 巡检窗口与指标
|
|
76
|
+
- 异常 EP 摘要表(EP、指标、值、阈值、时间、coverage、Top 错误码)
|
|
77
|
+
- 正常 EP 数量与零流量 EP
|
|
78
|
+
- 数据缺口与查询失败
|
|
79
|
+
- 证据链接/路径
|
|
80
|
+
- 推送回读(消息 ID、文档 token、Base record)
|
|
81
|
+
|
|
82
|
+
## 失败处理
|
|
83
|
+
|
|
84
|
+
- 清单只解析到部分分页:不发送“全量正常”,标 `partial` 并说明缺失范围。
|
|
85
|
+
- `errors` 为 `partial`:说明哪些查询失败,不把缺失错误码当成零错误。
|
|
86
|
+
- 推送失败:重试一次;仍失败则写本地报告并通知失败接收人。
|
|
87
|
+
- 同一天重复执行:用幂等键去重;不重复发相同摘要。
|
|
88
|
+
|
|
89
|
+
## 示例提示词
|
|
90
|
+
|
|
91
|
+
“每天 10 点巡检我名下所有 EP 过去 24 小时的错误率和 P99,有异常的推到群里,没异常也发一句摘要。”
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# 工作流验收场景
|
|
2
|
+
|
|
3
|
+
这些是行为验收,不代表线上已通过。能力面的数值验证仍以 `arkcli-vmp/references/evals.md` 为准。
|
|
4
|
+
|
|
5
|
+
| 场景 | 期望行为 |
|
|
6
|
+
|---|---|
|
|
7
|
+
| “盯住 ep-a、ep-b 半小时,错误率超过 1% 推群里” | 选 vmp-rollout-watch;先基线,再有界 watch;检查 end;按 EP 判定;推送前确认接收方;报告首次越界时间 |
|
|
8
|
+
| “每天 10 点巡检所有 EP,发日报” | 选 vmp-daily-digest;先解析全部分页;固定 24h 窗口;异常与缺口分开;按 scheduler 契约注册;不宣称 CLI 内建调度 |
|
|
9
|
+
| “比较 14:00 发布前后各 30 分钟” | 选 vmp-release-compare;直接用 `doctor monitor compare --start/--end --baseline-start/--baseline-end`;等长不重叠;coverage 门槛内才给 pass/violation,否则 inconclusive;不写因果 |
|
|
10
|
+
| “最近十四天峰值,容量够不够” | 选 vmp-capacity-review;固定 336h、1m step/range;20161 点;`doctor monitor capacity` 输出逐 EP utilization 与 ok/warning/critical/inconclusive,引用 assumptions |
|
|
11
|
+
| “ep-a 错误率 5%,是限流还是超时” | 选 vmp-incident-drilldown;窄窗复现;doctor infer-endpoint;错误分布;事实/假设分开 |
|
|
12
|
+
| “帮我配一个错误率告警” | 选 vmp-alert-provision;确认标品 CN;读模板与版本;展示 `vmp.create_alerting_rule_group` 参数并确认;写后 `alert list` 回读;不虚构规则 ID;投递验证单列为待控制台验证 |
|
|
13
|
+
| “在 TT 等非标品环境上给这个 EP 配告警” | 反唤起:ArkCLI 不覆盖;不调用 VMP 告警 API;说明边界并给对应控制台路径 |
|
|
14
|
+
| 只问“这个月用了多少 token” | 反唤起:转 arkcli-usage |
|
|
15
|
+
| 只问“ep-a 报 429 怎么办” | 反唤起:转 arkcli-doctor |
|
|
16
|
+
| 没有飞书权限/未给接收方 | 只落本地报告;明确“尚未发送”;不标记 verified |
|
|
17
|
+
| watch 中途取消或没有 end | 保留已有样本;标 cancelled/partial;不宣称持续监控 |
|
|
18
|
+
| 推送成功但文档写入失败 | 分别记录 side_effects;不把部分成功写成全部成功 |
|
|
19
|
+
| 同一天重复执行日报 | 幂等键命中;不重复发送;run.json 保留两次记录 |
|
|
20
|
+
|
|
21
|
+
## Trigger / anti-trigger / guard
|
|
22
|
+
|
|
23
|
+
- Trigger:包含“盯放量、定时巡检、发布对比、容量复盘、异常下钻、推送到飞书”等编排意图。
|
|
24
|
+
- Anti-trigger:单次查询、纯诊断、纯用量/账单、Endpoint 写操作。
|
|
25
|
+
- Guard:认证按 `arkcli-shared`;发送前确认接收方和内容;写操作前确认授权;失败保留证据。
|
|
26
|
+
|
|
27
|
+
## Happy path
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
arkcli doctor monitor snapshot --endpoint ep-a,ep-b --window 10m --range 1m --format json
|
|
31
|
+
arkcli doctor monitor watch --endpoint ep-a,ep-b --window 5m --range 1m --step 15s --interval 30s --duration 30m --summary-only --format jsonl
|
|
32
|
+
lark-cli im +messages-send --chat-id oc_xxx --markdown @report.md --idempotency-key vmp-rollout-20261108
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
验收点:显式 EP 集、统一时间网格、end 记录、逐 EP 判定、消息 ID 回读、run.json 与报告一致。
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# 飞书集成
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
飞书是编排面的副作用适配器,不是能力面。`arkcli` 只产出证据;本文件描述如何把证据变成消息、文档、Base/Sheet 记录,并回读结果。
|
|
6
|
+
|
|
7
|
+
## 前置检查
|
|
8
|
+
|
|
9
|
+
- 已安装并登录 `lark-cli`(或宿主提供等价的飞书工具)。
|
|
10
|
+
- 机器人在目标群;文档/Base/Sheet 有对应权限。
|
|
11
|
+
- 发送前展示目标、标题、摘要和证据链接,取得用户确认。
|
|
12
|
+
- 每次副作用使用幂等键,避免重复发送。
|
|
13
|
+
|
|
14
|
+
## 消息推送
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
lark-cli im +messages-send --chat-id oc_xxx --markdown @report.md --idempotency-key vmp-daily-2026-11-08
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- `--chat-id` 与 `--user-id` 二选一;群聊用 `oc_`,个人用 `ou_`。
|
|
21
|
+
- 发送后保存返回的 message ID;失败时保留本地报告,重试一次。
|
|
22
|
+
- 没有 `lark-cli` 时,输出可直接粘贴的 Markdown,并标记“尚未发送”。
|
|
23
|
+
|
|
24
|
+
## 文档落盘
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
lark-cli docs +create --title "VMP 日报 2026-11-08" --content @report.md --doc-format markdown
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- 已存在文档时用 `docs +update` 的 `block_replace`/`append`,不要整篇覆盖。
|
|
31
|
+
- 回读 document token 和 revision;报告里给出链接。
|
|
32
|
+
- 复杂表格用 DocxXML,普通摘要用 Markdown。
|
|
33
|
+
|
|
34
|
+
## 多维表格 / 电子表格
|
|
35
|
+
|
|
36
|
+
- 巡检记录、EP 清单与收藏优先用 Base:`lark-cli base +record-batch-create` / `+record-upsert`。
|
|
37
|
+
- 指标明细用 Sheet:`lark-cli sheets +cells-set` 或 `+csv-put`。
|
|
38
|
+
- 写入前确认 app token、table id、字段映射;写入后回读 record id 或 range。
|
|
39
|
+
- 具体参数以 `lark-cli skills read lark-base` / `lark-sheets` 为准,不在本文件复制完整命令目录。
|
|
40
|
+
|
|
41
|
+
## 副作用契约
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"type": "feishu_message",
|
|
46
|
+
"target": "oc_xxx",
|
|
47
|
+
"title": "VMP 日报 2026-11-08",
|
|
48
|
+
"idempotency_key": "vmp-daily-2026-11-08",
|
|
49
|
+
"result": {"ok": true, "message_id": "om_xxx"},
|
|
50
|
+
"verified": true
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
- `verified=true` 只在拿到平台返回 ID 或回读成功后设置。
|
|
55
|
+
- 发送失败、权限不足、目标不存在时,`verified=false`,并在报告里写明“未发送/未写入”。
|
|
56
|
+
|
|
57
|
+
## 失败处理
|
|
58
|
+
|
|
59
|
+
- 鉴权失败:转 `lark-shared` / `lark-cli auth login`,不要重试到封禁。
|
|
60
|
+
- 群不存在或无权限:请求用户提供正确的 chat_id 或邀请机器人。
|
|
61
|
+
- 文档写入部分成功:保留 revision 和已写入 block,报告 partial,不重复整篇覆盖。
|
|
62
|
+
- 网络错误:重试一次;仍失败则保留本地报告并通知失败接收人。
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# 异常下钻(vmp-incident-drilldown)
|
|
2
|
+
|
|
3
|
+
## 何时使用
|
|
4
|
+
|
|
5
|
+
放量盯盘、每日巡检或用户已经发现异常,需要继续定位到具体 EP、错误类型、时延或配额压力。
|
|
6
|
+
|
|
7
|
+
## 必填输入
|
|
8
|
+
|
|
9
|
+
- 异常 EP、时间点或时间窗。
|
|
10
|
+
- 已知指标和阈值。
|
|
11
|
+
- 是否允许读取 Trace/日志;可用的 request_id 或错误码。
|
|
12
|
+
|
|
13
|
+
## 执行
|
|
14
|
+
|
|
15
|
+
1. 先确认异常事实:用 `collect` 在窄窗口复现,保存 `evidence/anomaly.json`。不要直接沿用摘要里的聚合值。
|
|
16
|
+
2. 单 EP 诊断:按 `arkcli-doctor` 的真实入口执行 `arkcli doctor infer-endpoint <ep>`,检查状态、用量、错误率、配额压力。
|
|
17
|
+
3. 错误分布:先用原子下钻命令拿逐 EP 错误码 Top N、请求量和排查建议:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
arkcli doctor monitor errors --endpoint ep-a --window 1h --top-codes 5 --format json > evidence/errors.json
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`vmp.errors.v1` 的 `results[].codes[]` 含 `code`、`http_status_code`、`api`、`count`、`share`;`hints[]` 是按错误码规则生成的建议,不是根因结论。需要自定义分组(例如按 model/api 交叉)时,再用 `arkcli doctor metrics run --id request.error.distribution --param by=...`。错误率上升不等于限流,必须看错误码分布。
|
|
24
|
+
4. 异步/离线请求:显式查询 `async.gateway.*`;默认五项不含这些指标。
|
|
25
|
+
5. 需要 Trace/日志时,只使用宿主实际可用的工具;没有就保留为待补充证据。
|
|
26
|
+
6. 区分事实、假设和未知;不要从 EP 聚合指标推断某一次请求的根因。
|
|
27
|
+
7. 输出时间线、证据、假设、下一步;本 Skill 只读,不改配额、不切模型、不停止 EP。
|
|
28
|
+
|
|
29
|
+
## 判定
|
|
30
|
+
|
|
31
|
+
- `confirmed`:有可复查的指标/错误分布/诊断证据支持。
|
|
32
|
+
- `hypothesis`:有线索但缺少关键证据。
|
|
33
|
+
- `inconclusive`:数据不足、覆盖不足或无法关联单次请求。
|
|
34
|
+
|
|
35
|
+
## 报告模板
|
|
36
|
+
|
|
37
|
+
- 异常时间线与 EP
|
|
38
|
+
- 复现命令与证据路径
|
|
39
|
+
- 指标/错误码分布
|
|
40
|
+
- 诊断输出摘要
|
|
41
|
+
- 事实 / 假设 / 未知
|
|
42
|
+
- 建议的下一步与所需授权
|
|
43
|
+
|
|
44
|
+
## 失败处理
|
|
45
|
+
|
|
46
|
+
- 无法复现:说明窗口和口径,不宣布“已恢复”。
|
|
47
|
+
- 只有 request_id:按 `arkcli-doctor` 的边界说明无法反查单条日志,请求补充错误码/资源 ID/时间。
|
|
48
|
+
- 需要写操作:转对应能力 Skill,并先给出影响和确认点。
|
|
49
|
+
|
|
50
|
+
## 示例提示词
|
|
51
|
+
|
|
52
|
+
“ep-a 刚才错误率突然到 5%,帮我看是限流、超时还是模型错误,给出证据和下一步。”
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# 发布前后对比(vmp-release-compare)
|
|
2
|
+
|
|
3
|
+
## 何时使用
|
|
4
|
+
|
|
5
|
+
用户要在一次发布、模型切换或配置变更前后,比较同一组 EP 的指标是否退化。
|
|
6
|
+
|
|
7
|
+
## 必填输入
|
|
8
|
+
|
|
9
|
+
- EP 集合与发布时刻 T。
|
|
10
|
+
- 前后窗口长度(等长、不重叠)。
|
|
11
|
+
- 指标、step、range。
|
|
12
|
+
- 判定口径:哪些变化算退化,流量差异如何处理。
|
|
13
|
+
|
|
14
|
+
## 执行
|
|
15
|
+
|
|
16
|
+
1. 读 [collect](../../arkcli-vmp/references/collect.md) 与 [指标语义](../../arkcli-vmp/SKILL.md#能力边界)。
|
|
17
|
+
2. 冻结两个区间:发布前 `[T-L, T)`;发布后从 `T + range` 开始,避免统计回看跨越边界。两段等长、不重叠。
|
|
18
|
+
3. 优先使用原子对比命令,不要在 Agent 侧重复实现 diff:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
arkcli doctor monitor compare \
|
|
22
|
+
--endpoint ep-a,ep-b \
|
|
23
|
+
--metric rpm,error_rate,latency \
|
|
24
|
+
--start <post-start> --end <post-end> \
|
|
25
|
+
--baseline-start <pre-start> --baseline-end <pre-end> \
|
|
26
|
+
--step 1m --range 1m \
|
|
27
|
+
--format json > evidence/compare.json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
只给当前窗口时,baseline 默认取紧邻的前一个等长窗口:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
arkcli doctor monitor compare --endpoint ep-a,ep-b --metric rpm,error_rate,latency \
|
|
34
|
+
--window 30m --step 1m --range 1m --format json > evidence/compare.json
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
4. 判定阈值用显式参数固定并随输出回显:
|
|
38
|
+
|
|
39
|
+
| Flag | 默认 | 含义 |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `--min-coverage` | `0.8` | 两侧覆盖率低于该值时不可判定 |
|
|
42
|
+
| `--max-error-rate-delta` | `0.01` | 错误率允许的绝对增幅(1 个百分点) |
|
|
43
|
+
| `--max-latency-delta-pct` | `20` | 时延均值允许的相对增幅 |
|
|
44
|
+
| `--min-rpm-ratio` | `0.5` | 流量低于基线的该比例时判为流量塌陷 |
|
|
45
|
+
|
|
46
|
+
5. 读取 `vmp.compare.v1`:`status`、`thresholds`、`assumptions`、`baseline`/`current` 证据、逐 EP `metrics[]` 的 `sample_mean`/`peak`/`coverage`/`delta`/`delta_pct`/`verdict`/`reason`。
|
|
47
|
+
6. 退出码即判定:`pass` 为 0;`violation`、`inconclusive`、`no_data`、`failed` 均为非零,但 JSON 已先输出。CI 可直接用退出码卡发布。
|
|
48
|
+
|
|
49
|
+
## 判定
|
|
50
|
+
|
|
51
|
+
- `pass`:两侧证据充分、覆盖率达标,且没有超过阈值的退化。
|
|
52
|
+
- `violation`:在有效样本上出现明确退化(错误率、时延或流量塌陷)。
|
|
53
|
+
- `inconclusive`:区间不等长、口径不一致、覆盖不足、缺少样本或流量不可比。
|
|
54
|
+
- `no_data` / `failed`:窗口内没有可用数据或全部查询失败;不得写成“发布无影响”。
|
|
55
|
+
|
|
56
|
+
## 口径限制
|
|
57
|
+
|
|
58
|
+
- `sample_mean` 是采样点的算术平均,不是按请求加权的错误率,也不是全时段 pooled P99。
|
|
59
|
+
- 错误率阈值是绝对比例差(`0.01` = 1 个百分点),不是相对变化。
|
|
60
|
+
- `--min-rpm-ratio` 只是流量塌陷守卫,不知道流量下降是否是发布预期;判 violation 前向用户确认。
|
|
61
|
+
- `compare` 不比较 `quota.purchased.tpm` 之外的业务配额口径;需要自定义规则时,用两次 `collect` 保存原始证据后在 Agent 侧计算,并在报告里写明公式。
|
|
62
|
+
|
|
63
|
+
## 报告模板
|
|
64
|
+
|
|
65
|
+
- 发布时刻、前后区间、EP 清单
|
|
66
|
+
- 指标、step/range、单位、阈值
|
|
67
|
+
- 逐 EP 前后 `sample_mean`/峰值与变化、覆盖率、流量
|
|
68
|
+
- `verdict` 与 reason、首次越界项
|
|
69
|
+
- 证据路径(`evidence/compare.json`)、限制与下一步
|
|
70
|
+
|
|
71
|
+
## 失败处理
|
|
72
|
+
|
|
73
|
+
- 发布后区间早于 `T + range`:无效对比,重选区间。
|
|
74
|
+
- 两段 EP 集或指标不一致:无效对比,重新采集。
|
|
75
|
+
- 只有一段有数据:标 `inconclusive`,不写“发布无影响”。
|
|
76
|
+
- 覆盖不足:先扩大窗口或降低 step,不要直接放行。
|
|
77
|
+
|
|
78
|
+
## 示例提示词
|
|
79
|
+
|
|
80
|
+
“比较 ep-a、ep-b 在 14:00 发布前后各 30 分钟,错误率和 P99 有没有退化,生成飞书报告。”
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# 放量盯盘(vmp-rollout-watch)
|
|
2
|
+
|
|
3
|
+
## 何时使用
|
|
4
|
+
|
|
5
|
+
用户要在一段时间内盯住一组 EP,按阈值判断放量是否继续,并在异常时收到通知。
|
|
6
|
+
|
|
7
|
+
## 必填输入
|
|
8
|
+
|
|
9
|
+
- EP 集合(1–50/批;更多分批,同一 start/end)。
|
|
10
|
+
- 观察时长、轮询间隔、每轮 window/step/range。
|
|
11
|
+
- 指标与阈值(例如错误率 > 1%、E2E P99 > 2s、输出 TPM > 配额 80%)。
|
|
12
|
+
- 接收方(飞书群/个人/文档)和是否授权发送。
|
|
13
|
+
|
|
14
|
+
缺阈值时只报告变化,不判定通过。缺接收方时只落本地报告。
|
|
15
|
+
|
|
16
|
+
## 执行
|
|
17
|
+
|
|
18
|
+
1. 读 [`../arkcli-vmp/SKILL.md`](../../arkcli-vmp/SKILL.md)、[watch](../../arkcli-vmp/references/watch.md) 与 [collect](../../arkcli-vmp/references/collect.md)。
|
|
19
|
+
2. 解析 EP 和身份;保存清单来源与解析时间。
|
|
20
|
+
3. 基线:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
arkcli doctor monitor snapshot --endpoint ep-a,ep-b --window 10m --range 1m --format json
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
保存为 `evidence/baseline.json`。
|
|
27
|
+
|
|
28
|
+
4. 启动观察。把用户阈值直接翻译成 `--alert-on`,让 CLI 在每轮采样后做确定性判断;事件流里只有状态切换才出 `alert` 记录:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
arkcli doctor monitor watch --endpoint ep-a,ep-b --window 5m --range 1m --step 15s --interval 30s --duration 30m --summary-only --alert-on 'error_rate>0.01,latency>2.0' --alert-for 3 --format jsonl
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
保存为 `evidence/watch.jsonl`。每条 sample 带 sequence/status/collection;`type=alert` 带 endpoint/metric/value/threshold/consecutive_samples/state(firing/resolved);end 为 completed/cancelled/failed,并带 `active_alerts`。结束时仍有 firing 告警,命令以非零退出,编排层据此触发通知或停止放量;退出码非零时要先读 `active_alerts` 和事件流,不要直接归因于采集失败。
|
|
35
|
+
|
|
36
|
+
EP 集合若来自“我的/某模型/名称前缀”,用 `--mine/--model/--name-regex/--status` 隐式解析(与 `--endpoint` 互斥);解析结果在 `scope` 里,启动时只解析一次。阈值语义见 [watch](../../arkcli-vmp/references/watch.md)。
|
|
37
|
+
|
|
38
|
+
## 负载与安全
|
|
39
|
+
|
|
40
|
+
watch 每个 sample 发 `metrics × 时间分片` 次查询,EP 数量不放大查询数。默认 `--max-qps 2`;`--interval` 不得低于 `metrics / max-qps`(5 个指标、2 QPS → 至少 2.5s,建议取整到 3s),低于下限直接报错,不会先打满再限流。每轮采集完成后才等待 interval,不会并发堆积。先用 `--plan` 看每轮和总查询数:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
arkcli doctor monitor watch --endpoint ep-a,ep-b --interval 30s --duration 30m --plan
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
429/5xx 有界退避;连续失败按 partial/failed 记录,不要把限流误判成业务异常。多进程/多用户同时盯盘时,各自遵守自己的 `--max-qps`,不要对同一工作区开很多 1s 间隔的 watch。
|
|
47
|
+
|
|
48
|
+
5. 每轮按判据检查。异常样本记录 sequence、时间、EP、指标、值、阈值、coverage 和 query。
|
|
49
|
+
6. 异常 EP 用 `arkcli doctor infer-endpoint <ep>` 或 `arkcli doctor metrics` 下钻;不要用同一份聚合值反复推断。
|
|
50
|
+
7. 观察结束后检查 end 记录;`completed` 只表示时间结束,不表示健康。
|
|
51
|
+
8. 生成 `report.md`,按 [飞书集成](feishu.md) 推送。
|
|
52
|
+
|
|
53
|
+
## 判定
|
|
54
|
+
|
|
55
|
+
- `pass`:所有轮次、所有 EP 的指标都在阈值内,且 coverage 足够;零流量不能算 pass。
|
|
56
|
+
- `violation`:任一 EP 在有效样本上越过阈值;记录首次越界时间和持续轮次。
|
|
57
|
+
- `inconclusive`:缺 end、partial/no_data、coverage 不足、阈值口径不明确或流量不足。
|
|
58
|
+
|
|
59
|
+
## 报告模板
|
|
60
|
+
|
|
61
|
+
- 目标与判据
|
|
62
|
+
- EP 清单与解析时间
|
|
63
|
+
- 基线(窗口、流量、覆盖率)
|
|
64
|
+
- 观察范围与轮次
|
|
65
|
+
- 逐 EP 结果(pass/violation/inconclusive)
|
|
66
|
+
- 首次异常时间线、指标、值、阈值、证据路径
|
|
67
|
+
- 诊断与建议
|
|
68
|
+
- 副作用回读(消息 ID/文档 token)
|
|
69
|
+
|
|
70
|
+
## 失败处理
|
|
71
|
+
|
|
72
|
+
- watch 没有 end:报告截断,保留已有样本,不宣称持续监控。
|
|
73
|
+
- 推送失败:保留 `report.md`,重试一次;仍失败则标记 `side_effect_failed`,不写“已通知”。
|
|
74
|
+
- 用户中途改阈值:新开 run,不覆盖旧证据。
|
|
75
|
+
|
|
76
|
+
## 示例提示词
|
|
77
|
+
|
|
78
|
+
“盯住 ep-a、ep-b 半小时,每 30 秒看一次最近 5 分钟,错误率超过 1% 或 P99 超过 2 秒就推到这个群。”
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# 运行记录(arkcli.workflow.run.v1)
|
|
2
|
+
|
|
3
|
+
每个工作流 run 写一份 `run.json`,作为报告、调度和复盘的事实源。
|
|
4
|
+
|
|
5
|
+
```json
|
|
6
|
+
{
|
|
7
|
+
"schema": "arkcli.workflow.run.v1",
|
|
8
|
+
"workflow": "vmp-rollout-watch",
|
|
9
|
+
"run_id": "20261108T153000+0800-abc123",
|
|
10
|
+
"started_at": "2026-11-08T15:30:00+08:00",
|
|
11
|
+
"finished_at": "2026-11-08T16:00:00+08:00",
|
|
12
|
+
"status": "completed",
|
|
13
|
+
"profile": "prod",
|
|
14
|
+
"product": "volc",
|
|
15
|
+
"scope": {
|
|
16
|
+
"endpoints": ["ep-a", "ep-b"],
|
|
17
|
+
"inventory_source": "user-provided",
|
|
18
|
+
"resolved_at": "2026-11-08T15:29:50+08:00"
|
|
19
|
+
},
|
|
20
|
+
"window": {
|
|
21
|
+
"start": "2026-11-08T15:30:00+08:00",
|
|
22
|
+
"end": "2026-11-08T16:00:00+08:00",
|
|
23
|
+
"step": "15s",
|
|
24
|
+
"range": "1m"
|
|
25
|
+
},
|
|
26
|
+
"criteria": {
|
|
27
|
+
"error_rate": {"op": ">", "value": 0.01},
|
|
28
|
+
"latency_p99_ms": {"op": ">", "value": 2000}
|
|
29
|
+
},
|
|
30
|
+
"evidence": [
|
|
31
|
+
"evidence/baseline.json",
|
|
32
|
+
"evidence/watch.jsonl"
|
|
33
|
+
],
|
|
34
|
+
"result": {
|
|
35
|
+
"verdict": "violation",
|
|
36
|
+
"summary": "ep-b error rate crossed 1% at 15:47:30+08:00"
|
|
37
|
+
},
|
|
38
|
+
"side_effects": [
|
|
39
|
+
{
|
|
40
|
+
"type": "feishu_message",
|
|
41
|
+
"target": "oc_xxx",
|
|
42
|
+
"idempotency_key": "vmp-rollout-20261108",
|
|
43
|
+
"result": {"ok": true, "message_id": "om_xxx"},
|
|
44
|
+
"verified": true
|
|
45
|
+
}
|
|
46
|
+
],
|
|
47
|
+
"errors": [],
|
|
48
|
+
"next_steps": ["check ep-b upstream latency", "decide whether to pause rollout"]
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 字段规则
|
|
53
|
+
|
|
54
|
+
- `status`:`completed` / `partial` / `failed` / `cancelled`。
|
|
55
|
+
- `verdict`:`pass` / `violation` / `inconclusive` / `confirmed` / `hypothesis` / `planned`。
|
|
56
|
+
- `evidence`:相对 run 目录的路径;不得引用不存在的文件。
|
|
57
|
+
- `side_effects`:没有执行就写空数组;失败写 `verified=false` 和错误。
|
|
58
|
+
- `errors`:保留原始错误摘要,不只写“失败”。
|
|
59
|
+
- `run_id`:时间戳 + 随机后缀;同一任务重跑生成新 ID,不覆盖旧目录。
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# 定时执行
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
CLI 没有内建调度器。定时巡检由宿主(cron、CI、飞书任务、Agent 宿主)触发;本文件定义任务契约,避免每个工作流各写一套调度逻辑。
|
|
6
|
+
|
|
7
|
+
## 任务规格
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"schema": "arkcli.workflow.job.v1",
|
|
12
|
+
"workflow": "vmp-daily-digest",
|
|
13
|
+
"profile": "prod",
|
|
14
|
+
"product": "volc",
|
|
15
|
+
"scope": {"type": "project", "endpoint_source": "control-plane"},
|
|
16
|
+
"lookback": "24h",
|
|
17
|
+
"thresholds": {"error_rate": 0.05, "p99_ms": 2000},
|
|
18
|
+
"timezone": "Asia/Shanghai",
|
|
19
|
+
"schedule": "0 10 * * *",
|
|
20
|
+
"recipients": ["oc_xxx"],
|
|
21
|
+
"idempotency_key": "vmp-daily-{date}",
|
|
22
|
+
"max_runtime": "20m",
|
|
23
|
+
"on_failure": {"notify": ["ou_xxx"], "keep_evidence": true}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 执行约定
|
|
28
|
+
|
|
29
|
+
1. 每次运行创建独立 `runs/<workflow>/<run-id>/`,写 `run.json`。
|
|
30
|
+
2. 同一 workflow + profile + 日期只允许一个成功 run;用锁文件或幂等键去重。
|
|
31
|
+
3. 超时、查询失败、推送失败分别记录;不要用一个 `failed` 覆盖所有原因。
|
|
32
|
+
4. 失败时保留证据并通知失败接收人;不要发送“全量正常”的摘要。
|
|
33
|
+
5. 时区、下次运行时间、job id 必须回读并记录;没有回读就不算注册成功。
|
|
34
|
+
|
|
35
|
+
## cron 示例
|
|
36
|
+
|
|
37
|
+
```cron
|
|
38
|
+
0 10 * * * cd /path/to/workdir && flock -n runs/vmp-daily.lock ./run-vmp-daily.sh >> runs/cron.log 2>&1
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`run-vmp-daily.sh` 是宿主包装脚本,职责固定为:读取 job.json → 调用 `arkcli doctor monitor` → 写 run.json/report.md → 调用飞书适配器 → 按退出码通知。脚本不复制采集逻辑,也不在 CLI 外拼 PromQL:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
#!/usr/bin/env bash
|
|
45
|
+
set -euo pipefail
|
|
46
|
+
run_id="$(date +%Y%m%dT%H%M%S)-$(openssl rand -hex 3)"
|
|
47
|
+
dir="runs/vmp-daily/$run_id"; mkdir -p "$dir/evidence"
|
|
48
|
+
eps="$(jq -r '.scope.endpoints | join(",")' job.json)"
|
|
49
|
+
window="$(jq -r '.lookback' job.json)"
|
|
50
|
+
# 1) 采集:失败也保留已写出的 JSON
|
|
51
|
+
arkcli doctor monitor snapshot --endpoint "$eps" --window "$window" --range 1m --format json > "$dir/evidence/snapshot.json"
|
|
52
|
+
arkcli doctor monitor errors --endpoint "$eps" --window "$window" --top-codes 5 --format json > "$dir/evidence/errors.json"
|
|
53
|
+
# 2) 判定与报告:由 Agent 或 jq 生成 $dir/report.md;禁止把 partial/no_data 写成正常
|
|
54
|
+
# 3) 推送:幂等键 = workflow + date;发送后回读 message_id
|
|
55
|
+
lark-cli im +messages-send --chat-id "$(jq -r '.recipients[0]' job.json)" \
|
|
56
|
+
--markdown @"$dir/report.md" --idempotency-key "vmp-daily-$(date +%F)"
|
|
57
|
+
# 4) 留档:run.json 写入 status/verdict/evidence/side_effects
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## 失败处理
|
|
61
|
+
|
|
62
|
+
- 清单解析失败:不发送摘要,标 `failed`,通知失败接收人。
|
|
63
|
+
- 部分批次失败:标 `partial`,发送时明确缺失范围。
|
|
64
|
+
- 推送失败:数据结论保留,标 `side_effect_failed`。
|
|
65
|
+
- 同一日期重复触发:幂等键命中则跳过发送,不重复写文档;`flock` 防止并发重入。
|
|
66
|
+
|
|
67
|
+
## 边界
|
|
68
|
+
|
|
69
|
+
- 本文件不承诺 ArkCLI 内建调度、任务 ID 或运行历史。
|
|
70
|
+
- 飞书任务/日历只作为宿主触发入口;其权限和可用性单独验证。
|