@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
|
@@ -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
|
+
- 飞书任务/日历只作为宿主触发入口;其权限和可用性单独验证。
|