@volcengine/ark-cli-win32-arm64 1.0.56-prerelease.6094ee0f05e7 → 1.0.59-prerelease.9abfd7059045

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.
@@ -1,4 +1,4 @@
1
1
  [diffend] Oversized file quarantined before diffing.
2
2
  name: package/bin/arkcli-windows-arm64.exe
3
- size: 40156672 bytes
4
- sha256: 07e895dcfcd702e6deeee0551e578b3d4bac36542fa3d94f0547a54088b22940
3
+ size: 40219648 bytes
4
+ sha256: 88605789890563a813caef2b777a1c68884d687e9167d25d712d17e4ae496e85
package/manifest.json CHANGED
@@ -1,37 +1,37 @@
1
1
  {
2
- "version": "1.0.56-prerelease.6094ee0f05e7",
2
+ "version": "1.0.59-prerelease.9abfd7059045",
3
3
  "platforms": {
4
4
  "darwin-amd64": {
5
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.56-prerelease.6094ee0f05e7/arkcli-1.0.56-prerelease.6094ee0f05e7-darwin-amd64",
6
- "sha256": "5216437bf7c76b8666ea14781ed0b304d4d71ab46ded064ca33e9579ff3dee11"
5
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.59-prerelease.9abfd7059045/arkcli-1.0.59-prerelease.9abfd7059045-darwin-amd64",
6
+ "sha256": "ea704e0c3ebd2fa64109d4ddaa7b583b5cf6aea668525e34cf27a25dbf148ad4"
7
7
  },
8
8
  "darwin-arm64": {
9
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.56-prerelease.6094ee0f05e7/arkcli-1.0.56-prerelease.6094ee0f05e7-darwin-arm64",
10
- "sha256": "fd045b6b9844e905cd46fcaa297138839034baa617085fa55c4e180c2142fcb6"
9
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.59-prerelease.9abfd7059045/arkcli-1.0.59-prerelease.9abfd7059045-darwin-arm64",
10
+ "sha256": "8277ff426022680be339ccbba5a3a32b38d60672d77d3f9b23a3d93ddd546147"
11
11
  },
12
12
  "linux-amd64": {
13
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.56-prerelease.6094ee0f05e7/arkcli-1.0.56-prerelease.6094ee0f05e7-linux-amd64",
14
- "sha256": "0d1c2b5441cf0e56c33b93161be7e64fb230fbe6a6926a8179f165972de1d26b"
13
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.59-prerelease.9abfd7059045/arkcli-1.0.59-prerelease.9abfd7059045-linux-amd64",
14
+ "sha256": "b7caea26557fe32d9a7b96d4ef816c5ae20d603aff73ad95b1b894952d0623c7"
15
15
  },
16
16
  "linux-arm64": {
17
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.56-prerelease.6094ee0f05e7/arkcli-1.0.56-prerelease.6094ee0f05e7-linux-arm64",
18
- "sha256": "4987b0702a74de06148476c94fcb7bd482951d19c9db1917c4cfa5e7e88e2c13"
17
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.59-prerelease.9abfd7059045/arkcli-1.0.59-prerelease.9abfd7059045-linux-arm64",
18
+ "sha256": "ab5bca5cb61af1ec75baef22cf02d01a0d2a85bed4537e3055b5e035ce8f77dc"
19
19
  },
20
20
  "windows-amd64": {
21
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.56-prerelease.6094ee0f05e7/arkcli-1.0.56-prerelease.6094ee0f05e7-windows-amd64.exe",
22
- "sha256": "3912780048f14785b977d0d63172b82fda4debe6bf54f8b7104f22378b856cf1"
21
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.59-prerelease.9abfd7059045/arkcli-1.0.59-prerelease.9abfd7059045-windows-amd64.exe",
22
+ "sha256": "0190fdc45a0a12d5b07d57b227ff86f1e3fa35759bc886765ce2ec0f064bc09f"
23
23
  },
24
24
  "windows-arm64": {
25
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.56-prerelease.6094ee0f05e7/arkcli-1.0.56-prerelease.6094ee0f05e7-windows-arm64.exe",
26
- "sha256": "07e895dcfcd702e6deeee0551e578b3d4bac36542fa3d94f0547a54088b22940"
25
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.59-prerelease.9abfd7059045/arkcli-1.0.59-prerelease.9abfd7059045-windows-arm64.exe",
26
+ "sha256": "88605789890563a813caef2b777a1c68884d687e9167d25d712d17e4ae496e85"
27
27
  }
28
28
  },
29
29
  "skills": {
30
30
  "primary": {
31
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.56-prerelease.6094ee0f05e7/skills.tar.gz",
32
- "sha256": "4a45b9a4c6ae3287cfe5dc87c6e62e6c3b919676a4100a132659f1c36f6d1e64",
31
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.59-prerelease.9abfd7059045/skills.tar.gz",
32
+ "sha256": "230e1c5c0e08ea8ab26c9c8eeb4a6aca12b364f1e9410587a59153a8bfc1f11a",
33
33
  "kind": "cdn"
34
34
  },
35
- "tag": "v1.0.56-prerelease.6094ee0f05e7"
35
+ "tag": "v1.0.59-prerelease.9abfd7059045"
36
36
  }
37
37
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@volcengine/ark-cli-win32-arm64",
3
- "version": "1.0.56-prerelease.6094ee0f05e7",
3
+ "version": "1.0.59-prerelease.9abfd7059045",
4
4
  "description": "ArkCLI volc binary and Skills for windows-arm64",
5
5
  "os": [
6
6
  "win32"
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: arkcli-agent
3
- version: 1.1.5
4
- description: "arkcli agent:管理 ARK Managed Agents,包括 Agent / Skill / Env / Session / File / Memory Store / Vault / MCP OAuth。控制面优先走 ForTop/OpenTOP,Session 运行时和 Files 走数据面直联。"
3
+ version: 1.1.6
4
+ description: "arkcli agent:管理 ARK Managed Agents,包括 Agent / Skill / Env / Session / Deployment / File / Memory Store / Vault / MCP OAuth。控制面优先走 ForTop/OpenTOP,InitEvents 创建、Deployment、Session 运行时和 Files 走数据面直联。"
5
5
  metadata:
6
6
  requires:
7
7
  bins: ["arkcli"]
@@ -79,6 +79,9 @@ Environment 还是 Session。用户提供明确 ID 时直接查对应资源,
79
79
  | 扫描或导入 GitHub Skill | `agent skill github scan <repo>` / `agent skill github import <repo> --path ...|--all` | [`references/skills.md`](references/skills.md#from-github-import) |
80
80
  | 管理 custom Skill 版本 / 删除 Skill | 先完整列出版本,再按“非 latest → latest → Skill”的依赖顺序删除 | [`references/skills.md`](references/skills.md) |
81
81
  | 创建运行环境 / 会话 | `arkcli agent env ...` / `arkcli agent session ...` | [`references/session-files.md`](references/session-files.md) |
82
+ | 浏览器模板 / 环境构建脚本 / 规格(仅火山) | Env create/update `--template-id --build-script --spec`;新 Session 的 Environment override | [`references/session-files.md#云环境模板构建脚本与规格火山`](references/session-files.md#云环境模板构建脚本与规格火山) |
83
+ | 创建会话时立即提交任务(仅火山) | `agent session create --initial-events @events.json`;不是创建后再 send | [`references/session-files.md#创建-session-时提交-initevents火山`](references/session-files.md#创建-session-时提交-initevents火山) |
84
+ | 保存、定时或手动运行任务(仅火山) | `agent deployment create/update/list/get/pause/unpause/archive/run`;`runs list/get` | [`references/interfaces-gaps.md#deployment火山`](references/interfaces-gaps.md#deployment火山) |
82
85
  | 自托管环境 / Work Queue 排障与停止任务 | `agent env create --runtime-type self_hosted` / `agent env work list/get/stats/stop` | [`references/self-hosted.md`](references/self-hosted.md) |
83
86
  | Environment 初始化脚本 | `arkcli agent env create/update --setup-script @./bootstrap.sh` | [`references/session-files.md`](references/session-files.md#environment-自定义脚本) |
84
87
  | Session 一次性覆盖 Agent / Environment | `arkcli agent session create --agent-overrides ... --environment-overrides ...` | [`references/session-files.md`](references/session-files.md#session-overrides) |
@@ -94,6 +97,7 @@ Environment 还是 Session。用户提供明确 ID 时直接查对应资源,
94
97
  | 只上传 / 查询 Files API 文件 | `arkcli agent file upload/list/get/wait/delete` | [`references/session-files.md`](references/session-files.md) |
95
98
  | 管理 memory store / memories | `arkcli agent memory-store ...` | [`references/interfaces-gaps.md`](references/interfaces-gaps.md) |
96
99
  | 整理会话记忆、创建或观察 Dream 任务(仅火山) | `arkcli agent dream create/list/get/cancel/wait` | [`references/dream.md`](references/dream.md) |
100
+ | 订阅资源变更/运行状态、配置回调与排查投递(仅火山) | `arkcli agent webhook ...` / `agent webhook events list/get`;不是 Channel,也不是 Session token 流 | [Webhook 指引](references/interfaces-gaps.md#webhook仅火山) |
97
101
  | 查询可挂载 MCP / 管理 Vault / Credential / MCP OAuth | `arkcli agent vault oauth-provider list` / `arkcli agent vault ...` / `arkcli agent +mcp-login ...` | [`references/mcp-vault.md`](references/mcp-vault.md) |
98
102
  | 创建 ENV OAuth 凭证(火山) | 已有 token 用 `agent vault credentials create --auth-type env_oauth`;浏览器授权用 `agent vault env-oauth-flow create`,完成后查凭证确认 | [`references/mcp-vault.md`](references/mcp-vault.md) |
99
103
 
@@ -147,7 +151,7 @@ Environment 还是 Session。用户提供明确 ID 时直接查对应资源,
147
151
 
148
152
  - Dream 创建不自动重试。超时、连接中断或响应解析失败都可能已创建任务;先用返回 ID 查询,未拿到 ID 时检查 `agent dream list`,不要直接重新创建。`dream wait` 超时或中断只停止本地等待,不取消远端任务。
149
153
 
150
- - 只对网络超时、连接中断、429 或 5xx 做有限重试;参数校验、鉴权失败、未开通、权限不足和明确业务错误直接抛出,不要重试。
154
+ - 只读请求可对网络超时、连接中断、429 或 5xx 做有限重试;参数校验、鉴权失败、未开通、权限不足和明确业务错误直接抛出,不要重试。InitEvents 创建与 Deployment 写请求不自动重试,结果不明时先只读核实,避免重复触发任务。
151
155
  - `session create` 超时后结果可能未知。先用 `session list/get` 按返回的标题、Agent、环境和创建时间检查是否已经创建,再决定是否重试;没有幂等键时不要盲目重复创建。
152
156
  - `events send` 超时后也可能已经被服务端接收。先用返回的 event cursor、发送时间或最近的 user event 查询 `events list`;确认没有接收记录后才允许重试,避免重复发送用户消息。
153
157
  - `events send --stream` 达到 stream 等待上限后自动转为 events list polling,默认再等待 120 秒。两阶段都超时后只读恢复,不重发;再次执行 `events send --poll` 会发送新消息,不是续等。
@@ -165,6 +169,8 @@ Environment 还是 Session。用户提供明确 ID 时直接查对应资源,
165
169
  | `arkcli agent skill search/list/get/create/update/delete/versions/download/set-protection/github` | Market/custom/Ark Skill 查询、GitHub 导入、custom Skill 保护与版本管理;Ark Skill 只读 |
166
170
  | `arkcli agent env list/get/create/update/delete` | Environment CRUD;火山支持 `--include-archived` / `--status`,状态筛选规则见 `session-files.md` |
167
171
  | `arkcli agent session list/get/create/update/delete` | Session CRUD |
172
+ | `arkcli agent deployment create/update/list/get/pause/unpause/archive/run` | 火山 Deployment;create 保存不运行,run 受理不等于模型完成 |
173
+ | `arkcli agent deployment runs list/get` | 火山运行记录;关联 Session 后继续检查 events |
168
174
  | `arkcli agent session upgrade <session-id>` | 升级已有 Session 运行配置,返回受理状态;使用 snake_case 请求并回读验证 |
169
175
  | `arkcli agent session resources list/add/get` | 数据面 session resources;get 是 CLI 基于 list 的本地筛选 |
170
176
  | `arkcli agent session events list/send/stream` | 数据面 events;stream 默认请求 Event Deltas 并输出 SSE/NDJSON 行;`--no-event-deltas` 回退完整事件;`user.custom_tool_result` 必须带 `custom_tool_use_id`,`user.tool_result` 仅允许 self_hosted,CLI 会前置校验 |
@@ -186,7 +192,7 @@ Environment 还是 Session。用户提供明确 ID 时直接查对应资源,
186
192
  | `arkcli +debug <session-id>` | 聚合 session、events、resources、threads 做诊断 |
187
193
  | `arkcli +export <session-id>` | 导出诊断 tar.gz |
188
194
 
189
- 复杂字段如 `Tools`、`Skills`、`McpServers`、`Multiagent`、`Metadata`、`Tags` 支持 JSON/YAML 文件、stdin 或结构化 flags。TOP 请求使用 CamelCase,inline 对象兼容常见 lower/snake case alias;`session upgrade` 是例外,使用原生 snake_case,只读取显式文件/flags,不自动读取 stdin。创建成功回显必须展示服务端最终的身份、模型、`System`、Tools、Skills、MCP 和扩展配置,不能只展示摘要;需要核对完整结果时用 `agent agent get <agent-id> --format json` 或 `--format yaml`。
195
+ 复杂字段如 `Tools`、`Skills`、`McpServers`、`Multiagent`、`Metadata`、`Tags` 支持 JSON/YAML 文件、stdin 或结构化 flags。TOP 请求使用 CamelCase,inline 对象兼容常见 lower/snake case alias;`session upgrade` 和 `deployment` 使用原生 snake_case,只读取显式文件/flags,不自动读取 stdin。`session create --initial-events` 的事件数组也是原生 snake_case;其余 Session flags 沿用现有格式,CLI 转换到 Open 请求。创建成功回显必须展示服务端最终的身份、模型、`System`、Tools、Skills、MCP 和扩展配置,不能只展示摘要;需要核对完整结果时用 `agent agent get <agent-id> --format json` 或 `--format yaml`。
190
196
 
191
197
  Memory get 的 `--view` 语义:默认按 `basic` 请求,只返回 metadata 和 `ContentSha256`;`--view full` 保留 Content。若服务端仍在 basic 下返回 Content,CLI 会在输出层剥离 Content,但这只能控制输出,不能挽回已经产生的网络传输;服务端仍需正确实现 View 参数以节省带宽。
192
198
 
@@ -1,5 +1,17 @@
1
1
  # arkcli-agent 2026-08 最小评估用例
2
2
 
3
+ ## Deployment / InitEvents / 环境模板(release/20261027)
4
+
5
+ - 要求每天执行任务:明确持续运行授权,查询真实 Agent/Env,创建 Deployment + 五段 cron/IANA 时区;不把创建成功当作已执行,不额外手动 run。
6
+ - run 返回 session_id/error 都空:只读查询原 Run;error 非空报告启动失败,session_id 非空继续核对 Session events,不凭 HTTP 200/退出码 0 宣称任务完成。
7
+ - 更新移除计划与 Vault:schedule=null、vault_ids=[],保留未提供字段;initial_events=null 不当作清空,明确后端不允许。
8
+ - 列表 next_page 是 opaque+/=:原样传 --page,不当数字加一;--page-limit 为最大页数。
9
+ - 创建时带 initial_events:使用普通 Key 和 MA 地址,解析顶层 id;不再发送重复 user.message,超时先按标题/资源/时间核实。
10
+ - 仅预览:Deployment 写命令与 Session/Env create/update 零网络;不触发登录、开通、初始化或 run。
11
+ - browser 环境保存成功:不声称预构建完成;检查新 Session 快照与实际脚本效果,不手工拼 playwright-cli Skill ID。
12
+ - self_hosted 要求 build-script,或已有 Session 要升级 spec:说明不支持,不偷偷改成 cloud/新建 Session。
13
+ - 要求零资源创建:说明当前后端 release 不支持,不能编造 inline 协议;经用户授权才分步创建真实资源。
14
+
3
15
  ## ENV OAuth 凭证(火山)
4
16
 
5
17
  - 用户要求浏览器授权后将 token 注入 Skill:查询 `CredentialType=env_oauth` 的真实 provider,调用 `agent vault env-oauth-flow create`,不用 `+mcp-login`,不要求 MCP URL。
@@ -130,3 +130,201 @@ CLI 在 Connection=failed 或获取应用配置时增加顶层 `Guidance`,包
130
130
  - 前端的 `StreamManagedAgentSessionEvents` 仍是 ArkBFF 的 POST 流式 preview 协议。CLI 按“不直连 ArkBFF”的约束直联数据面,因此只对齐已确认的数据面 Event Deltas 语义,不依赖或宣称复用 BFF preview 的请求封装。
131
131
  - `[MA]开通时支持赠送额度包` 在需求单当前状态为已终止,现有 OpenTOP 仅有人工确认后的 `OpenChargeItems`,没有可确认的 gift quota 字段/Action;CLI 保持手动确认开通,不自动伪造赠送额度。
132
132
  - “企业自定义 Skill”若指当前账号/项目下的 custom Skill,CLI 已通过 TOP `ListSkills` 选择并以 `Type=custom` 挂载;若要求额外企业 Skill 空间/组织 scope,当前公开 `ListSkills` 请求契约没有可确认的 enterprise/space 字段,不能硬接。现有 `--skill-space-id` 不代表后端已支持该过滤字段。
133
+
134
+ ## Deployment(火山)
135
+
136
+ Deployment 保存可重复启动 Session 的任务配置。创建不运行;每次手动或定时触发产生独立 Run 和 Session。本组命令仅适用于火山产品。
137
+
138
+ ### 创建与执行
139
+
140
+ 先确认真实 Agent/Environment/资源归属及任务授权。全部命令使用 MA Open 数据面与普通 Platform API Key;只提供显式 Key 时使用 MA 标准地址,显式地址必须同时提供显式 Key,不使用模型 BYOK BaseUrl。
141
+
142
+ ```bash
143
+ arkcli agent deployment create --name daily-summary \
144
+ --agent-id <agent-id> --environment-id <env-id> \
145
+ --initial-events '[{"type":"user.message","content":[{"type":"text","text":"整理今日待办。"}]}]' \
146
+ --format json
147
+ arkcli agent deployment get <deployment-id> --format json
148
+ arkcli agent deployment run <deployment-id> --format json
149
+ arkcli agent deployment runs get <run-id> --format json
150
+ ```
151
+
152
+ 用户只要求保存配置时,不顺便 run。不默认加 schedule;定时执行可能持续产生模型/沙箱费用,须明确获准。
153
+
154
+ | 参数 | 说明 |
155
+ | --- | --- |
156
+ | `--name` / `--description` | 名称/描述;描述更新空串或文件中的 null 表示清空 |
157
+ | `--agent-id` / `--agent-version` | 既有 Agent;version flag 须同时给 agent-id;未指定版本时服务端在保存时解析并固定当前版本,不是每次 run 自动跟随最新版 |
158
+ | `--environment-id` | 既有环境 ID;不接受 inline Env,不提供 Agent override |
159
+ | `--initial-events` | JSON/YAML 数组或 @file;1–50 条 user.message 或单条 user.define_outcome,不混用;更新不可 null/空数组,省略保留 |
160
+ | `--resources` / `--vault-ids` / `--tags` | JSON/YAML 数组或 @file;不是逗号分隔。resources/vault_ids 更新 null/[] 清空,数组整体替换 |
161
+ | `--schedule` | `{type: cron, expression: "0 9 * * *", timezone: Asia/Shanghai}`;严格五段 cron、IANA 时区;更新 null 移除,省略保留 |
162
+ | `--file` | 原生 Open snake_case JSON/YAML 对象;显式 flags 覆盖对应字段,不读取隐式 stdin,不接受 `--file -` |
163
+
164
+ 完整文件的 agent 可为 ID 字符串,或 `{"type":"agent","id":"...","version":3}`。resources 使用 `type/file_id/memory_store_id/access/mount_path/tos_bucket/tos_key/tos_region`;tags 为 `[{"key":"...","value":"..."}]`,不要沿用 TOP PascalCase。参数合法性、权限与资源可用性以服务端校验为准。
165
+
166
+ ```bash
167
+ arkcli agent deployment update <deployment-id> \
168
+ --schedule '{type: cron, expression: "0 9 * * *", timezone: Asia/Shanghai}' --format json
169
+ arkcli agent deployment pause <deployment-id> --format json
170
+ arkcli agent deployment unpause <deployment-id> --format json
171
+ arkcli agent deployment update <deployment-id> --schedule null --vault-ids '[]' --format json
172
+ arkcli agent deployment archive <deployment-id> --yes --format json
173
+ ```
174
+
175
+ pause 只暂停计划触发,仍允许手动 run;unpause 不补跑错过的任务。archive 不可恢复,需要明确确认再带 --yes;它不会替用户终止已创建的 Session。更新只影响之后的 Run,不改已有 Session 快照。
176
+
177
+ ### 查询与结果判断
178
+
179
+ ```bash
180
+ arkcli agent deployment list --agent-id <agent-id> --include-archived --limit 20 --format json
181
+ arkcli agent deployment runs list --deployment-id <deployment-id> --has-error=false --limit 20 --format json
182
+ arkcli agent session list --deployment-id <deployment-id> --format json
183
+ ```
184
+
185
+ - list 支持 status(active/paused)、search(完整 ID 或名称关键词)、created-at-gte/lte;runs list 还支持 trigger-type(manual/schedule)、created-at-gt/lt。时间为 RFC3339。
186
+ - Open 列表为 `data` 和 `next_page`;`--page` 是不透明游标,照抄 next_page,不加一。`--limit` 是每页条数(Deployment 最大 100,Run 最大 1000);`--page-all` 自动翻页,`--page-limit` 是最大页数。达到页数上限时仍检查 next_page,不能说全量查完。
187
+ - 所有返回值为原生 snake_case。run 的 `error` 非空表示启动失败,CLI 返回非零;保存 Run ID,先 `runs get` 排查。`session_id` 和 `error` 均空表示尚未完成启动,不能算成功或重新 run。
188
+ - `session_id` 非空仅表示 Session 与 initial_events 受理,继续查对应 Session 的 events,才能判断模型/工具任务是否完成。`runs get/list` 是只读状态查询,退出码 0 不抹掉历史记录中的 error。
189
+ - 所有写请求禁自动重试。超时/断连时先用 Run ID 查询;有 Deployment ID 时列该 Deployment 的运行记录核对时间,不自动重发 run。只有配置保存成功,不代表 Cron 已执行。
190
+ - 写命令支持 `--dry-run`,只生成本地请求计划,不查询状态、不执行归档或启动任务;真实执行仍需独立授权。
191
+
192
+ ## Webhook(仅火山)
193
+
194
+ 把当前账号、Region、Project 下的资源变更和运行状态异步投递到用户的 HTTP(S) 接收地址。
195
+ 这是项目级订阅,不是某个 Session 的 callback 参数,也不是飞书 Channel;不携带模型 token、工具输出或完整资源快照。
196
+ 仅火山产品提供这些命令。接口以服务端实际部署为准;404 不应通过换账号、改 URL 或猜接口绕过。
197
+
198
+ ### 开始前
199
+
200
+ 1. 按主 Skill 的认证流程确认当前账号、Region、Project,使用普通 Platform Profile。控制面走 OpenTOP/STS,不需要为 Webhook 额外申请模型 API Key。
201
+ 2. 确认用户拥有或明确授权该接收地址,以及允许把本项目选定事件的资源 ID 发往该地址。不要使用临时第三方收集站接收真实项目事件。
202
+ 3. 先 `arkcli agent webhook list --format json` 查重,再确认 URL、订阅类型和密钥文件保存位置。每个项目最多 20 个端点(含已禁用的端点)。
203
+ 4. 接收方必须能验签、去重并快速返回 2xx。CLI 不启动接收服务器、不自动修改用户的服务器代码。
204
+
205
+ ### 命令与字段
206
+
207
+ 所有命令都限定在当前 Profile 的 Region / Project;单次切换使用 `--profile <platform-profile>`,输出可用 `--format json`。
208
+ 根命令不支持 `--project-name` / `--region`;需要新上下文时按 Profile Skill 创建或选择 Profile,不往 Webhook 请求文件中塞 ProjectName/Region。
209
+
210
+ | 命令 | 参数/结果 |
211
+ | --- | --- |
212
+ | `agent webhook create` | 必传 `--url`、`--events`、`--secret-file`;可传 `--description`、`--file`;返回 `Result.Id`(`wep-*`) |
213
+ | `agent webhook list` | 可选 `--status ACTIVE\|DISABLED`;`Result` 是数组,不分页 |
214
+ | `agent webhook get <endpoint-id>` | 回读 URL、Events、Status、失败计数和最近投递信息,不返回密钥 |
215
+ | `agent webhook update <endpoint-id>` | 至少传 `--url`、`--events`、`--description` 或对应 `--file` 字段之一;未传字段保留 |
216
+ | `agent webhook enable/disable <endpoint-id>` | 启用/禁用;启用只影响后续事件,不重放历史,不恢复已取消投递 |
217
+ | `agent webhook delete <endpoint-id> --yes` | 删除端点、清除签名密钥、取消待投递任务,需用户授权 |
218
+ | `agent webhook reset-secret <endpoint-id> --secret-file <new-path> --yes` | 立即轮换,旧密钥立即失效;协调接收端同步换钥 |
219
+ | `agent webhook test <endpoint-id> --yes` | 真实发送 `webhook.test` 测试事件;返回 `Result.Id`(`whe-*`)只代表入队 |
220
+ | `agent webhook events list <endpoint-id>` | 可选 `--limit`(每页 1–100)、`--page`(不透明游标)、`--event-id`、`--event-type`;结果为 `Result[]`、`NextPage` |
221
+ | `agent webhook events get <endpoint-id> <event-id>` | 查询事件与该端点对应的 `Result.Delivery`,用于判断是否真的投递成功 |
222
+
223
+ `--events` 可重复或用逗号分隔;**更新时全量替换订阅列表**,不是追加。
224
+ `--description ''` 清空描述;更新文件中的 `"Description":null` 同样清空,未提供才是保留。
225
+ `Url` / `Events` 不接受 null;URL 和事件枚举有效性由后端校验,CLI 不另设枚举白名单。
226
+ URL 默认受服务端公网安全策略限制;支持 HTTP/HTTPS,推荐 HTTPS;不跟随重定向,私网需服务端账号策略放行。
227
+
228
+ `--file` 为本地 JSON/YAML(不接受 `-`),只支持 `Url` / `Events` / `Description`;flags 覆盖同名字段。
229
+ EndpointId 用位置参数,Project/Region 由选定的 Profile 提供,不写入文件;这能避免用错项目/端点。
230
+
231
+ ```json
232
+ {
233
+ "Url": "https://receiver.example.com/ark-events",
234
+ "Events": ["session.status_idled", "session.error"],
235
+ "Description": "项目运行状态通知"
236
+ }
237
+ ```
238
+
239
+ ### 创建 → 测试 → 验收
240
+
241
+ 以下 URL 是占位符,必须替换成用户授权的真实接收地址。先选择一个新的私密密钥文件路径,父目录须已存在;不要把路径放进项目仓库或共享目录。
242
+
243
+ ```bash
244
+ arkcli agent webhook create --file ./webhook.json \
245
+ --secret-file /absolute/private/path/webhook-signing-secret --dry-run
246
+
247
+ arkcli agent webhook create --file ./webhook.json \
248
+ --secret-file /absolute/private/path/webhook-signing-secret --format json
249
+
250
+ arkcli agent webhook get <返回的wep-id> --format json
251
+ ```
252
+
253
+ 创建/重置返回的 `SigningSecret` 只保存到指定文件(0600、不覆盖),stdout 不打印密钥,仅给出 `SecretFile` 路径。
254
+ 不要 `cat`、回显或粘贴密钥到对话;通过用户认可的密钥部署方式交给接收服务,不能在未配置验签时宣布可用。
255
+
256
+ 完成接收端配置并获准实际发送后:
257
+
258
+ ```bash
259
+ arkcli agent webhook test <wep-id> --yes --format json
260
+ arkcli agent webhook events get <wep-id> <test返回的whe-id> --format json
261
+ ```
262
+
263
+ 检查 `Result.Delivery.Status`:
264
+
265
+ - `PENDING` / `RUNNING`:仍在处理,间隔几秒查询;给本地观察设置有限时长(例如 60 秒),到时仍未完成只报告待完成,不重复提交 test。
266
+ - `SUCCEEDED`:接收端返回 2xx;仍需核对接收端业务处理结果,2xx 不保证下游业务成功。
267
+ - `FAILED` / `CANCELED` / `EXPIRED`:没有成功;结合 `AttemptCount`、`LastErrorCode`、`FinishedAt` 和端点信息排查。
268
+ - `Delivery` 缺失或刚提交后短暂查询不到:尚不能判断成功,有限等待后保留 event ID 报告。
269
+
270
+ test 可在 DISABLED 端点执行,不自动启用、不更新业务投递统计,也不能证明所有业务事件已正常触发。
271
+ Webhook 事件 ID 与 Session 原始 event ID 不同,不把 `whe-*` 交给 `agent session events ...`。
272
+
273
+ ### 更新、分页与异常恢复
274
+
275
+ 改 URL 必须先禁用;确认影响后按下面顺序执行,CLI 不偷偷禁用/启用端点:
276
+
277
+ ```bash
278
+ arkcli agent webhook disable <wep-id> --format json
279
+ arkcli agent webhook update <wep-id> --url https://new-authorized.example.com/ark-events --format json
280
+ arkcli agent webhook get <wep-id> --format json
281
+ arkcli agent webhook test <wep-id> --yes --format json
282
+ # 核对该 test 的 Delivery 成功后,按用户意愿启用
283
+ arkcli agent webhook enable <wep-id> --format json
284
+ ```
285
+
286
+ 事件列表沿用全局 `--page-all`、`--page-limit`(最大页数,不是每页大小)、`--page-delay`。
287
+ 复用响应中的 `NextPage`,不要自行递增或解析;达到页数限制仍有 NextPage 代表尚未读完。
288
+
289
+ ```bash
290
+ arkcli agent webhook events list <wep-id> --event-type session.error --limit 20 --format json
291
+ arkcli agent webhook events list <wep-id> --event-type session.error --limit 20 --page '<NextPage原值>' --format json
292
+ ```
293
+
294
+ CLI 对 Webhook 写操作只发一次,不做自动重试。超时、断连、解析错误不代表未生效:
295
+
296
+ - 创建失败:先按已知端点 ID 回读,没拿到 ID 就 list 对照 URL/时间/描述,不能立刻再次 create。
297
+ - 创建/重置前会预留密钥文件;失败也保留它(可能为空)。不要用 `--secret-file` 覆盖旧文件来重试。
298
+ - 已创建但没拿到密钥,或已轮换但本地保存失败:确认实际端点、解决存储问题,获准后 `reset-secret` 到**另一个新文件**,同步接收端配置;不要假称可通过 get 再次读出旧密钥。
299
+ - `test` 的响应丢失:先查 `events list --event-type webhook.test`,不要自动补发。
300
+ - 跨项目、已删除或不存在的端点可能统一返回 404;先核实当前身份/Region/Project/ID,不用全账号遍历绕过资源隔离。
301
+
302
+ 服务端当前约定:单次回调超时 5 秒,最多 3 次尝试;投递窗口 24 小时、查询记录保留 7 天。
303
+ 达到连续业务失败阈值(20 次)可自动禁用;安全地址/重定向失败可立即禁用。
304
+ 这些是后端投递策略,不是 CLI `test` 的等待/重试参数。先排查 `DisabledReason`、`LastErrorCode`,不要反复 enable。
305
+
306
+ ### 当前可订阅事件
307
+
308
+ 以下来自后端 `release/20261027`;不代表部署环境必然已发布,也不是客户端硬编码校验列表。
309
+
310
+ | 类别 | 事件 |
311
+ | --- | --- |
312
+ | Session 运行 | `session.status_run_started`、`session.status_idled`、`session.status_terminated`、`session.error` |
313
+ | Thread / 评估 | `session.thread_status_running`、`session.thread_status_idle`、`session.thread_status_terminated`、`span.outcome_evaluation_end` |
314
+ | Session 记录 | `session.updated`、`session.deleted` |
315
+ | Agent | `agent.created`、`agent.updated`、`agent.deleted` |
316
+ | Environment | `environment.created`、`environment.updated`、`environment.deleted` |
317
+ | Memory Store | `memory_store.created`、`memory_store.deleted` |
318
+ | Vault | `vault.created`、`vault.deleted` |
319
+ | Credential | `vault_credential.created`、`vault_credential.deleted`、`vault_credential.refresh_failed` |
320
+
321
+ `webhook.test` 仅由 test 生成,不可加入订阅;不要凭名字编造 Deployment、Dream、token 流事件。
322
+ 通知包含资源定位信息;需要完整资源或事件正文时再按对应 Skill 查询。
323
+
324
+ ### 接收端验签约定
325
+
326
+ 请求头为 `Webhook-Id`、`Webhook-Timestamp`、`Webhook-Signature`。
327
+ 密钥去掉 `whsec_` 前缀后做标准 Base64 解码,得到 32 字节 key。
328
+ 使用 HMAC-SHA256 对 `id + "." + timestamp + "." + 原始HTTP请求体字节` 签名,结果标准 Base64 编码并加 `v1,` 前缀,与签名头做常量时间比较。
329
+ 时间戳为 Unix 秒,校验正负 5 分钟窗口;验签之前不要重新序列化正文。
330
+ 验签后按 `Webhook-Id` 去重,容忍重复和乱序,尽快返回 2xx,再异步处理业务。
@@ -1,6 +1,6 @@
1
1
  # Session 与 Files
2
2
 
3
- `session resources list/get/add` 是数据面命令,支持显式 `--api-key` / `--base-url`。显式地址必须同时提供显式 Key,且地址应为 MA 数据面地址,不是 BYOK 模型的 BaseUrl;只提供 Key 时使用当前产品、Region、环境的 MA 标准地址,不继承套餐路由。这不改变 `session create/get` 等控制面命令的认证要求。
3
+ `session resources list/get/add` 是数据面命令,支持显式 `--api-key` / `--base-url`。显式地址必须同时提供显式 Key,且地址应为 MA 数据面地址,不是 BYOK 模型的 BaseUrl;只提供 Key 时使用当前产品、Region、环境的 MA 标准地址,不继承套餐路由。普通 `session create/get` 仍使用控制面认证;带 InitEvents 的创建例外,认证规则见下文。
4
4
 
5
5
  ## Env / Session
6
6
 
@@ -19,7 +19,7 @@ arkcli agent session create --agent-id <agent-id> --environment-id <env-id> --ti
19
19
  arkcli agent session get <session-id> --format json
20
20
  ```
21
21
 
22
- Session 标准 CRUD 走 OpenTOP;Session resources / events / threads 走数据面直联。
22
+ Session 标准 CRUD 走 OpenTOP;火山 `session create` 显式提供 `--initial-events` 或完整请求的 `InitialEvents` 时改走 Open 数据面,返回 snake_case Session,见 [InitEvents](#创建-session-时提交-initevents火山)。Session resources / events / threads 走数据面直联。
23
23
  线上创建 cloud env 时需要显式带 `Networking: {Type: unrestricted}`;只传 `{Type: cloud}` 会被后端校验为缺少 `config.networking`。
24
24
 
25
25
  读取 Session 时保留 stdout、stderr 和退出码,先检查业务错误,再按实际 envelope 取字段:OpenTOP 通常为 `Result.Id` / `Result.AgentId`,其他入口可能包在 `data`;以完整 JSON 为准,不能把顶层 `.Id == null` 当作 Session 不存在。字段未回显、成功空结果、权限失败、鉴权失败和解析错误分别报告;已有完整响应只修正本地取值路径,不为取错层级重新查询,也不合并 stderr 后当 JSON 解析。
@@ -55,6 +55,8 @@ arkcli agent session create --agent-id <agent-id> --environment-id <env-id> \
55
55
 
56
56
  ### Environment 自定义脚本
57
57
 
58
+ 火山云环境另有 `TemplateId / BuildScript / Spec`,见 [模板、构建脚本与规格](#云环境模板构建脚本与规格火山)。BuildScript 用于预构建,SetupScript 用于 Session 初始化,不可混淆;self_hosted 不支持这些云环境字段。
59
+
58
60
  Environment 的初始化脚本位于 `Config.SetupScript`。可以直接传文本,也可以用 `@` 读取本地脚本文件:
59
61
 
60
62
  ```bash
@@ -156,3 +158,72 @@ arkcli agent session resources add sess-xxx --path ./sales.csv --mount-path sale
156
158
  ## 工具版本
157
159
 
158
160
  Session 的 AgentWithOverrides.Tools 是完整数组;不提供就沿用绑定 Agent 的配置,不自动升级旧工具集。显式选择 20260916 或提示词增强工具前,读取 [工具配置](agent.md#默认-agent-工具),保留完整的其他工具、权限与 Models。
161
+
162
+ ## 云环境模板、构建脚本与规格(火山)
163
+
164
+ 仅适用于火山产品的 cloud 环境。
165
+
166
+ | 参数 | 写入字段 | 语义 |
167
+ | --- | --- | --- |
168
+ | `--template-id base\|browser` | `Config.TemplateId` | 默认 base;browser 使用浏览器镜像,服务端向 Session 主 Agent 注入所配置版本的 playwright-cli Skill,不修改 Agent 资源;不要手工猜该 Skill ID |
169
+ | `--spec 1x\|2x\|4x\|8x` | `Config.Spec` | 依次为 2C4GiB、4C8GiB、8C16GiB、16C32GiB;不使用旧前端的 1C2GiB 映射或 16x |
170
+ | `--build-script <text\|@file>` | `Config.BuildScript` | UTF-8、无 NUL、最多 256KiB,整体 Config 还受服务端大小限制;更新省略/null 保留,空串清空 |
171
+
172
+ ```bash
173
+ arkcli agent env create --name browser-task \
174
+ --config '{Type: cloud, Networking: {Type: unrestricted}}' \
175
+ --template-id browser --spec 2x --build-script @./build.sh --format json
176
+ arkcli agent env get <env-id> --format json
177
+ arkcli agent env update <env-id> --build-script '' --format json
178
+ ```
179
+
180
+ 仅 `cloud` 支持上述配置。self_hosted 不传任何模板/规格/构建字段,包括空值;无效组合和枚举由服务端校验,不擅自修正后重放。更新环境先读取当前 Config 再合并显式字段;影响后续 Session,不改变已创建的快照。
181
+
182
+ 创建 Session 时可以一次性覆盖同样的字段:
183
+
184
+ ```bash
185
+ arkcli agent session create --agent-id <agent-id> --environment-id <env-id> \
186
+ --environment-overrides '{Config: {Type: cloud, TemplateId: browser, Spec: 2x, BuildScript: "echo prepare"}}' \
187
+ --format json
188
+ ```
189
+
190
+ 覆盖值只进入新 Session;不要使用 `session upgrade` 修改 TemplateId/BuildScript/Spec。复杂脚本放入完整 JSON/YAML 文件的 `Config.BuildScript`,对象内的 `@path` 不会展开。`--build-script @file` 才会读取本地脚本。
191
+
192
+ ### 如何判定成功
193
+
194
+ - Env 保存成功不代表镜像构建完成。保存会异步预热,失败不回滚资源;当前没有公开构建状态/日志查询命令,不编造 build wait/get。
195
+ - 预热依次安装 Packages、执行 BuildScript、再按标记规则执行 SetupScript;没有用户 Env 与资源挂载,脚本不能依赖这些输入。
196
+ - Session 冷启动注入 Env 后运行 Packages → BuildScript → SetupScript;有可用快照时可跳过前两项,SetupScript 仍按既有标记/hash 规则处理。失败可能发出 session.error 后继续初始化;“Session idle”不能证明脚本成功。
197
+ - 验证需检查 Session 的 Environment 快照、events 中的错误,并在沙箱执行最小检查(如 import 或版本查询)。不提供未实现的公网预览/屏幕 API,不把 browser 模板当成已经访问过网页。
198
+
199
+ ## 创建 Session 时提交 InitEvents(火山)
200
+
201
+ 适合“创建会话并立即执行任务”。使用现有 Agent/Environment ID,不是零资源创建。
202
+
203
+ ```bash
204
+ arkcli agent session create --agent-id <agent-id> --environment-id <env-id> \
205
+ --title task-<timestamp> \
206
+ --initial-events '[{"type":"user.message","content":[{"type":"text","text":"计算 17×23,简短回答。"}]}]' \
207
+ --format json
208
+ ```
209
+
210
+ `--initial-events` 接受 JSON/YAML 数组或 `@file`,事件必须使用 Open 的 snake_case。完整 `--file` 请求可用 `InitialEvents`(兼容 `initial_events`),其余 Session flags/overrides 原样使用,CLI 会映射到 Open 契约;显式 flag 覆盖文件相应字段。不会把事件正文中的键名/文字进行别名替换。
211
+
212
+ | 输入 | 行为 |
213
+ | --- | --- |
214
+ | 未提供 InitialEvents | 保留原 OpenTOP CreateSession 路径,不注入事件 |
215
+ | 显式 `[]` | Open 创建空会话,不自动发消息 |
216
+ | 非空数组 | 同一次 Open 创建请求提交初始事件,勿随后重复 send |
217
+ | `null` / 非数组 | 参数错误;不能表示“空事件” |
218
+
219
+ 后端允许最多 50 条 `user.message`,或单条 `user.define_outcome`;不混用两类。message content 可使用 text/image/document/video 等后端支持块,文件引用先按 Files 流程准备,不在远端请求中塞本地文件路径。define_outcome 需要 description、rubric,可带 max_iterations;格式参考 [事件说明](events-chat.md),不拼未支持的事件类型。
220
+
221
+ ### 认证与结果
222
+
223
+ - 此路径是 `POST /api/v3/sessions`,需普通 Platform API Key。仅控制面 SSO 不足以调用数据面;先按主 Skill 的认证流程检查,禁止使用 Agent Plan/Coding Plan 路由。
224
+ - 支持显式 `--api-key`;只有显式 Key 时按产品/Region/环境选择 MA 标准地址;显式 `--base-url` 必须配显式 Key,不使用 BYOK 模型 BaseUrl。
225
+ - Open 返回原生 `id / status / agent / environment`,不要按 TOP 的 `Result.Id` 取值。退出码 0 仅表示会话与初始事件受理,不等待回复、不表示模型/工具执行成功。
226
+ - 用返回的 Session ID 查 `session get` 与 `events list/stream`;确认本次 user event 和后续终态,按 [只读恢复](events-chat.md#异步发送后的只读恢复)处理旧事件/分页,不重复发送初始消息。
227
+ - 请求不自动重试。超时或断连后先按标题、Agent、环境、创建时间查询 Session;无法确认时报告“结果未知”,不要盲目再创建。`--dry-run` 只验证离线请求,不检验额度、权限和模型可用性。
228
+
229
+ `release/20261027` 尚不支持省略已有 Agent/Environment 的零资源创建。不要编造 inline Agent、inline Env 或自动创建默认资源来模拟该接口;可在用户明确授权后走分步创建流程。
@@ -72,6 +72,16 @@ runs/<workflow>/<run-id>/
72
72
 
73
73
  飞书适配器见 [飞书集成](references/feishu.md);宿主调度见 [定时执行](references/scheduler.md)。没有对应工具或权限时,输出可复制的消息/文档草稿,并明确“尚未发送”。
74
74
 
75
+ ## 定时任务(宿主)
76
+
77
+ 用户要求“每 N 小时/每天检查 last X”时,除常规冻结参数外:
78
+
79
+ 1. 创建前确认 project 的内部 ProjectName(不是展示名或近似名)和精确 EP ID 集合;有歧义先问用户。
80
+ 2. 冻结 `schedule`、`timezone`、`lookback/window`、`step`、`range`、`interval`、`duration`、指标和阈值。
81
+ 3. 创建后重新读取任务详情,逐项核对 project、EP、window、频率、时区和下次运行时间。
82
+ 4. 平台不支持用户要求的时间窗口或频率时,明确说明并让用户选择替代值;不能静默改成更大的窗口或更低的频率。
83
+ 5. 回读不一致时标记 `side_effect_failed`,保留创建回执,展示差异并给出修正步骤,不得宣称任务已按请求创建。
84
+
75
85
  ## 完成判据
76
86
 
77
87
  一个工作流只有同时满足以下条件才算完成:
@@ -6,6 +6,8 @@
6
6
  |---|---|
7
7
  | “盯住 ep-a、ep-b 半小时,错误率超过 1% 推群里” | 选 vmp-rollout-watch;先基线,再有界 watch;检查 end;按 EP 判定;推送前确认接收方;报告首次越界时间 |
8
8
  | “每天 10 点巡检所有 EP,发日报” | 选 vmp-daily-digest;先解析全部分页;固定 24h 窗口;异常与缺口分开;按 scheduler 契约注册;不宣称 CLI 内建调度 |
9
+ | “每 1 小时检查 ark_project_20250403_w9cgb 的 ep-xxx last 5mins 监控,创建定时任务” | 选 vmp-workflows;创建前用内部 ProjectName + 精确 EP ID 冻结参数;创建后回读 project、EP、lookback=5m、schedule=每小时、timezone、next_run_at;平台只支持更大窗口时明确让用户选择,不能静默改成 1h;回读不一致标 side_effect_failed |
10
+ | 创建定时任务后回读发现 project 从 `w9cgb` 变成 `dxqgb` 或 window 从 5m 变成 1h | 标 `side_effect_failed`;保留创建回执;展示回读差异并让用户确认修正;不得宣称任务已按请求创建 |
9
11
  | “比较 14:00 发布前后各 30 分钟” | 选 vmp-release-compare;直接用 `doctor monitor compare --start/--end --baseline-start/--baseline-end`;等长不重叠;coverage 门槛内才给 pass/violation,否则 inconclusive;不写因果 |
10
12
  | “最近十四天峰值,容量够不够” | 选 vmp-capacity-review;固定 336h、1m step/range;20161 点;`doctor monitor capacity` 输出逐 EP utilization 与 ok/warning/critical/inconclusive,引用 assumptions |
11
13
  | “ep-a 错误率 5%,是限流还是超时” | 选 vmp-incident-drilldown;窄窗复现;doctor infer-endpoint;错误分布;事实/假设分开 |
@@ -12,7 +12,7 @@ CLI 没有内建调度器。定时巡检由宿主(cron、CI、飞书任务、A
12
12
  "workflow": "vmp-daily-digest",
13
13
  "profile": "prod",
14
14
  "product": "volc",
15
- "scope": {"type": "project", "endpoint_source": "control-plane"},
15
+ "scope": {"type": "project", "project_name": "ark_project_...", "account_id": "101", "endpoint_source": "control-plane"},
16
16
  "lookback": "24h",
17
17
  "thresholds": {"error_rate": 0.05, "p99_ms": 2000},
18
18
  "timezone": "Asia/Shanghai",
@@ -30,7 +30,19 @@ CLI 没有内建调度器。定时巡检由宿主(cron、CI、飞书任务、A
30
30
  2. 同一 workflow + profile + 日期只允许一个成功 run;用锁文件或幂等键去重。
31
31
  3. 超时、查询失败、推送失败分别记录;不要用一个 `failed` 覆盖所有原因。
32
32
  4. 失败时保留证据并通知失败接收人;不要发送“全量正常”的摘要。
33
- 5. 时区、下次运行时间、job id 必须回读并记录;没有回读就不算注册成功。
33
+ 5. 时区、下次运行时间、job id 必须回读并记录;没有回读就不算注册成功。回读还必须覆盖实际生效的 project/account、EP 集合、lookback/window、step/range 和频率。
34
+
35
+ ## 创建后回读(必做)
36
+
37
+ 注册定时任务后,必须重新读取任务详情并逐项核对:
38
+
39
+ - `project_name` / `account_id`:内部标识,不是展示名或近似名;
40
+ - `endpoints`:精确 EP ID 集合;
41
+ - `lookback` / `window`、`step`、`range`;
42
+ - `schedule`、`timezone`、`next_run_at`;
43
+ - `job_id`、启用状态。
44
+
45
+ 任一项与冻结参数不一致时,标记 `side_effect_failed`,保留创建回执,向用户展示差异并给出修正步骤,不得宣称注册成功。平台不支持请求的窗口或频率时,先让用户选择替代值,不能静默替换。
34
46
 
35
47
  ## cron 示例
36
48
 
@@ -62,6 +74,7 @@ lark-cli im +messages-send --chat-id "$(jq -r '.recipients[0]' job.json)" \
62
74
  - 清单解析失败:不发送摘要,标 `failed`,通知失败接收人。
63
75
  - 部分批次失败:标 `partial`,发送时明确缺失范围。
64
76
  - 推送失败:数据结论保留,标 `side_effect_failed`。
77
+ - 创建后回读发现 project/EP/window/频率与请求不一致:标 `side_effect_failed`,保留创建回执,展示差异并让用户确认修正。
65
78
  - 同一日期重复触发:幂等键命中则跳过发送,不重复写文档;`flock` 防止并发重入。
66
79
 
67
80
  ## 边界