@volcengine/ark-cli-linux-x64 1.0.48-prerelease.9a272fcf7076 → 1.0.49-prerelease.60296d9213ad

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-linux-amd64
3
- size: 40210594 bytes
4
- sha256: bba5fa86c5628176f7fb4e21d2f9f5194f3eff941566b360121178ca36e49a61
3
+ size: 40403106 bytes
4
+ sha256: f9ffee18d1f3ec42087ea3ec36df57d76ba84c32761b0b103273192fcaf6e6f3
package/manifest.json CHANGED
@@ -1,37 +1,37 @@
1
1
  {
2
- "version": "1.0.48-prerelease.9a272fcf7076",
2
+ "version": "1.0.49-prerelease.60296d9213ad",
3
3
  "platforms": {
4
4
  "darwin-amd64": {
5
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.48-prerelease.9a272fcf7076/arkcli-1.0.48-prerelease.9a272fcf7076-darwin-amd64",
6
- "sha256": "363196acbefe138d64f8fd82e77ffc6c9a2c37944e1b31d9d036a537322c84e1"
5
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.49-prerelease.60296d9213ad/arkcli-1.0.49-prerelease.60296d9213ad-darwin-amd64",
6
+ "sha256": "e7578d18700a5a43cf0a6a747271c44f9865a9cc66af8320aa4a60a1ccc92848"
7
7
  },
8
8
  "darwin-arm64": {
9
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.48-prerelease.9a272fcf7076/arkcli-1.0.48-prerelease.9a272fcf7076-darwin-arm64",
10
- "sha256": "652c829cf31741f488b9cedf8b7af39ad3fc75370fa6006a0c5caea572cdfa6b"
9
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.49-prerelease.60296d9213ad/arkcli-1.0.49-prerelease.60296d9213ad-darwin-arm64",
10
+ "sha256": "4189830ea3df48997816a614148bd93877d03483f0308b1fcacdc8d304637190"
11
11
  },
12
12
  "linux-amd64": {
13
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.48-prerelease.9a272fcf7076/arkcli-1.0.48-prerelease.9a272fcf7076-linux-amd64",
14
- "sha256": "bba5fa86c5628176f7fb4e21d2f9f5194f3eff941566b360121178ca36e49a61"
13
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.49-prerelease.60296d9213ad/arkcli-1.0.49-prerelease.60296d9213ad-linux-amd64",
14
+ "sha256": "f9ffee18d1f3ec42087ea3ec36df57d76ba84c32761b0b103273192fcaf6e6f3"
15
15
  },
16
16
  "linux-arm64": {
17
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.48-prerelease.9a272fcf7076/arkcli-1.0.48-prerelease.9a272fcf7076-linux-arm64",
18
- "sha256": "2486345b1c77235aa7f6e9722a099aaf70dd5266df2cb52ba4357e0c9d53d6e2"
17
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.49-prerelease.60296d9213ad/arkcli-1.0.49-prerelease.60296d9213ad-linux-arm64",
18
+ "sha256": "aa80f342575870b06827548b81393845e6d4c2155f5d010222bffb4bd76d7f8e"
19
19
  },
20
20
  "windows-amd64": {
21
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.48-prerelease.9a272fcf7076/arkcli-1.0.48-prerelease.9a272fcf7076-windows-amd64.exe",
22
- "sha256": "4185303e888337c145d1af4319c4faf2d4b854f6d0e1d1dd88074ad5de04f79e"
21
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.49-prerelease.60296d9213ad/arkcli-1.0.49-prerelease.60296d9213ad-windows-amd64.exe",
22
+ "sha256": "916aaa6e96f383e49a010ef55ddd43703626cf70d9965fb0e77282871e33bb69"
23
23
  },
24
24
  "windows-arm64": {
25
- "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.48-prerelease.9a272fcf7076/arkcli-1.0.48-prerelease.9a272fcf7076-windows-arm64.exe",
26
- "sha256": "b4c77d229571dda214ceb0d32aada3f62afa6da7ddf6910678c295ebd5682c70"
25
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.49-prerelease.60296d9213ad/arkcli-1.0.49-prerelease.60296d9213ad-windows-arm64.exe",
26
+ "sha256": "c95a2af37653496b34fe051121b9bb993d0efb78cb71b911ec612a994ba366f8"
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.48-prerelease.9a272fcf7076/skills.tar.gz",
32
- "sha256": "1fca86ef0f0f0c87cd4083d1c10566abfbd3109e5dc575e5780cc417f774998b",
31
+ "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.49-prerelease.60296d9213ad/skills.tar.gz",
32
+ "sha256": "ad9287b7a493f620dc36460322ab83cea5321ea7910d3b0e0e53b4e579a291fb",
33
33
  "kind": "cdn"
34
34
  },
35
- "tag": "v1.0.48-prerelease.9a272fcf7076"
35
+ "tag": "v1.0.49-prerelease.60296d9213ad"
36
36
  }
37
37
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@volcengine/ark-cli-linux-x64",
3
- "version": "1.0.48-prerelease.9a272fcf7076",
3
+ "version": "1.0.49-prerelease.60296d9213ad",
4
4
  "description": "ArkCLI volc binary and Skills for linux-amd64",
5
5
  "os": [
6
6
  "linux"
@@ -63,6 +63,9 @@ Environment 还是 Session。用户提供明确 ID 时直接查对应资源,
63
63
  | ---- | ---- | ---- |
64
64
  | 仅开通 MA 服务(火山) | `arkcli agent activate`;不创建资源、不开通模型 | [`references/activation.md`](references/activation.md) |
65
65
  | 创建 / 更新 / 删除 Managed Agent | `arkcli agent agent ...` | [`references/agent.md`](references/agent.md) |
66
+ | 配置多 Agent 协作(仅火山新协议) | create/update `--multiagent`;Session `--agent-overrides` | [`Multiagent 配置`](references/agent.md#multiagent-配置) |
67
+ | 接入飞书 Channel(仅火山) | `arkcli agent channel ...` | [`Channel`](references/interfaces-gaps.md#channel火山) |
68
+ | 归档 Agent / Environment / Session(仅火山) | `agent agent/env/session archive <id> --yes` | [`归档`](references/session-files.md#归档火山) |
66
69
  | 启用 / 关闭 Todo 任务计划工具 | `agent agent create/update --tool`;非基础 toolset、不需要 Models | [`references/todo-write.md`](references/todo-write.md) |
67
70
  | 复制已有 Agent 并改名 / 局部覆盖配置 | `arkcli +new-agent --fork <agent-id> [--name <new-name>]` | [`references/agent.md`](references/agent.md#复制-agent) |
68
71
  | 为创建 Agent 选择可用模型 | `arkcli agent model list` | [`references/agent.md`](references/agent.md#模型选择) |
@@ -160,7 +163,7 @@ Environment 还是 Session。用户提供明确 ID 时直接查对应资源,
160
163
  | `arkcli +new-agent` | Agent create 增强入口;支持 `--fork/--from` 复制已有 Agent 后创建新 Agent |
161
164
  | `arkcli +iterate` | 更新 Agent 配置,创建新 Session,并进入 one-shot/REPL 试运行;创建前核对项目一致性,显式传入同 Project 的 `--environment-id/--env-id` |
162
165
  | `arkcli agent skill search/list/get/create/update/delete/versions/download/set-protection/github` | Market/custom/Ark Skill 查询、GitHub 导入、custom Skill 保护与版本管理;Ark Skill 只读 |
163
- | `arkcli agent env list/get/create/update/delete` | Environment CRUD;当前 `env list` 没有 `--status`,状态筛选规则见 `session-files.md` |
166
+ | `arkcli agent env list/get/create/update/delete` | Environment CRUD;火山支持 `--include-archived` / `--status`,状态筛选规则见 `session-files.md` |
164
167
  | `arkcli agent session list/get/create/update/delete` | Session CRUD |
165
168
  | `arkcli agent session upgrade <session-id>` | 升级已有 Session 运行配置,返回受理状态;使用 snake_case 请求并回读验证 |
166
169
  | `arkcli agent session resources list/add/get` | 数据面 session resources;get 是 CLI 基于 list 的本地筛选 |
@@ -425,6 +425,49 @@ arkcli agent agent create \
425
425
 
426
426
  如果用户要求多个工具不同策略,同样在这一个完整 `agent_toolset_20260916` 的 `Configs` 里同时改,不要拆成多个 `agent_toolset`。
427
427
 
428
+ ## Multiagent 配置
429
+
430
+ 本节新协议仅用于支持该功能的火山后端;BytePlus 不据此宣称已支持。
431
+ 新协议还有账号/项目级特性门禁。返回 `MultiagentNotEnabled` 时停止并说明当前 scope 未开放,不能用 MA 服务开通、切账号或自动降级成 coordinator 来绕过;`MultiagentPolicyUnavailable` 表示策略查询暂不可用,不等于未开白。更新时即使只改其他字段,只要最终配置仍保留新协议,也可能触发该门禁。
432
+ 创建与更新共用 `--multiagent '<JSON/YAML 对象>'` 或 `--multiagent @./multiagent.json`,完整请求文件使用 `Multiagent`。
433
+ 先读现有配置,不自动把旧 `coordinator` / `Agents` 转换成新协议。
434
+
435
+ ```json
436
+ {
437
+ "Type": "multiagent_20261001",
438
+ "Subagents": {
439
+ "Type": "enabled",
440
+ "InlineAgents": {"Type": "enabled"},
441
+ "PredefinedAgents": [
442
+ {"Type": "self"},
443
+ {"Type": "agent", "Id": "<已确认的-agent-id>", "Version": 1}
444
+ ]
445
+ }
446
+ }
447
+ ```
448
+
449
+ | 字段 | 含义与处理 |
450
+ | --- | --- |
451
+ | `Type` | 新协议 `multiagent_20261001`;旧协议值及 `Agents` 保持原样,不自动迁移 |
452
+ | `Subagents.Type` | `enabled` / `disabled`,是否允许子 Agent 能力 |
453
+ | `Subagents.InlineAgents.Type` | `enabled` / `disabled`,是否允许运行中动态定义子 Agent |
454
+ | `Subagents.PredefinedAgents` | 用户选定的完整 Agent 引用数组;`Type=agent` 使用真实 `Id` 和已确认版本;`Type=self` 表示复用自身,不是新建资源 |
455
+ | `Agents` | 旧协议字段,不能用它替代新协议的 `Subagents.PredefinedAgents` |
456
+
457
+ 省略、`null`、`[]` 不互换:更新省略 `Multiagent` 保留配置;显式 `--multiagent null` 向后端发送清除意图;`PredefinedAgents: []` 是显式空列表。嵌套字段省略与 `null` 原样传递,由后端执行当前版本的 patch 语义,不能一概解释成“合并”或“保留”。仅改模型时不要添加 `Multiagent: null`。
458
+
459
+ Session 的一次性覆盖写在 `--agent-overrides` 的 `Multiagent` 中,不修改原 Agent:
460
+
461
+ ```bash
462
+ ARKCLI_NO_UPDATE_NOTIFIER=1 ARKCLI_CALLER_TYPE=ai_agent ARKCLI_CALLER_NAME=codex ARKCLI_SKILL_NAME=arkcli-agent arkcli agent session create --agent-id <agent-id> --environment-id <env-id> --agent-overrides @./agent-overrides.json --format json
463
+ ```
464
+
465
+ 文件形如 `{"Multiagent":{"Type":"multiagent_20261001","Subagents":{"Type":"enabled","InlineAgents":{"Type":"enabled"},"PredefinedAgents":[]}}}`。引用的权限、循环依赖、模型兼容性由后端验证,CLI 不另做白名单拦截。创建/更新后必须 get 回读,配置保存成功不等于实际委派成功。
466
+
467
+ 运行时用已有 `session threads list/get` 和 `session events list/stream` 观察线程及任务事件,保留服务端的新字段。没有独立的 thread create/archive 命令。普通消息发给主线程;不要把面向整个 Session 的用户消息伪造成子线程输入。工具结果使用真实 `custom_tool_use_id`,服务端决定 owner;只有从事件确认归属时才传 `session_thread_id`,不要默认填主线程。
468
+
469
+ 等待整个 Session 时,子线程 idle/failed 不表示整个任务结束;显式按线程等待才使用该线程终态。需要人工审批时先处理审批,不宣称任务成功。中断线程与归档资源不同,不因一次子线程失败自动中断所有线程。
470
+
428
471
  ## 示例
429
472
 
430
473
  ```bash
@@ -216,6 +216,21 @@
216
216
  - FunctionNotAllowed:区分 Vision 开白与 MA 开通,不切账号、不降级类型、不重复创建。
217
217
  - 不将火山 Vision 模板套用到其他产品。未执行线上生图不得报告生图端到端通过。
218
218
 
219
+ ## Channel / Multiagent / 归档
220
+
221
+ - 用户要求接入已有飞书应用:读取 Channel reference,使用用户提供的应用、Agent 和 Environment;AppSecret 只通过安全文件或环境变量输入,不请求贴到对话。无测试应用时只做本地契约验证,不宣称飞书联通。
222
+ - Channel Credential=valid 但 Connection=pending:报告凭证有效、联通待验证,不把 Enabled=true 当成端到端成功。
223
+ - Channel 已返回 ID,但 Connection=failed、app_config_permission_denied:保留 ID,按 Guidance 导出配置并引导手动设置;不重复创建、不强求页面存在 application:application:patch 权限。
224
+ - app config 默认只显示 [REDACTED]:经授权导出新的私密文件,按 reference 对齐安全参数和事件/回调地址;不回显密钥,不把脱敏占位符填入页面。
225
+ - 页面报 Challenge code 没有返回:明确校验未通过,核对配置与服务端响应,不猜唯一原因;手动配置后 validate,再用真实飞书消息与关联 Session 验收。
226
+ - Channel 更新遇到版本冲突:保留冲突,不自动刷新版本重试;Policy 子对象与 SessionConfig 按后端替换规则提交,不把局部配置误当深合并。
227
+ - 应用注册仍 pending:按 PollInterval 有界查询,授权由用户完成;仅在明确要求导出时使用 --output 保存敏感结果,不回显正文。
228
+ - MultiagentNotEnabled:说明账号/项目特性门禁,不能用 agent activate 代替开白,也不能自行移除 Multiagent 或切账号。
229
+ - 等待 Session 时遇到 child thread idle/failed:继续观察 Session 终态和 usage;retrying 不判失败,不重发消息。
230
+ - 用户要求归档:核对具体资源和影响,经确认使用 archive,而不是 delete;归档受理后回读状态,不声称资源已物理删除,也不承诺可恢复。
231
+ - 用户查询已归档 Agent / Environment:使用 `--include-archived --status terminated`;单独 `--status terminated` 返回空时,补齐包含归档范围后再判断,不直接报告没有归档资源。Session 不套用 Agent/Environment 的状态枚举。
232
+ - 非火山产品:不生成本节火山专属 Channel、archive 命令,不把新 Multiagent 协议当作已支持能力。
233
+
219
234
  ## 独立开通 MA
220
235
 
221
236
  - 用户只要求开通 MA:选择 `agent activate`,不创建 Agent 或 Session,不查询或开通模型。
@@ -36,6 +36,83 @@
36
36
  - `+iterate` 已支持 GetAgent 当前版本 -> 可选 UpdateAgent -> CreateSession -> `--message` one-shot / TTY REPL;`--environment-id/--env-id` 是可选参数,未传时真实执行会用 `ListEnvironments` 自动选择当前项目最近创建的 Environment;没有可用环境才要求用户创建或显式传入。
37
37
  - 火山新建 Agent 不传 `--tool` 时发送 `agent_toolset_20260916`,含 bash/read/write/edit/glob/grep/web_fetch/web_search;传 `--tool` 时按完整数组全量覆盖。旧版本不自动升级;BytePlus 默认仍为 `agent_toolset_20260701`。
38
38
 
39
+ ## Channel(火山)
40
+
41
+ Channel 将飞书机器人消息路由到 Managed Agent Session,不是 CLI 自己监听飞书,也不是普通 Session 的别名。本节新命令仅在火山产品提供。
42
+
43
+ | 命令 | 用途 |
44
+ | --- | --- |
45
+ | `agent channel create --file ./channel.json` | 创建绑定;也支持 `--name`、`--provider`、`--app-id`、`--policy`、`--session-config`、`--enabled` |
46
+ | `agent channel get <id>` / `list` | 查询配置及 Validation;list 支持 `--name/--app-id/--agent-id/--provider/--enabled/--connection-status` |
47
+ | `agent channel update <id> --file ./patch.json` | 更新;`--enabled=false` 明确禁用;Provider 不可修改 |
48
+ | `agent channel delete <id> --yes` | 用户确认后删除绑定;不会删除历史 Session |
49
+ | `agent channel validate --file ./credentials.json` | 校验未保存的 Provider + FeishuApp;带 `--id <id>` 则校验并更新已保存 Channel 的验证状态 |
50
+ | `agent channel sessions list <id>` | 关联 Session 列表,支持 `--chat-type`、`--status`(重复)、`--keyword` |
51
+ | `agent channel participants list <id> --session-id <session-id>` | 参与者列表,可加 `--keyword`;Session 列表的 Participants 只是摘要,不能据此声称已列全 |
52
+ | `agent channel app register --app-name <name>` | 发起新应用注册,已有应用用 `--app-id`,两者不同时传 |
53
+ | `agent channel app status <registration-id>` | 单次查询注册状态;严格按返回 PollInterval 间隔查询,在 ExpireIn 内等待用户授权;不是自动授权 |
54
+ | `agent channel app config <id>` | 获取飞书应用回调/事件配置;默认脱敏;需要完整配置时按用户授权加 `--output ./private-channel.json` |
55
+
56
+ 所有命令支持显式 `--file` TOP JSON/YAML 对象;不隐式读取 stdin。列表使用 `--limit/--page`,`--page-all` 沿 NextPage 合并 `Result` 数组,并保留 Summary/ProjectionSyncedAt/ProjectionDelayed。ProjectionDelayed=true 表示投影延迟,不是会话不存在。
57
+
58
+ 创建请求示例(必须替换真实资源 ID,密钥不写在对话或命令参数中):
59
+
60
+ ```json
61
+ {
62
+ "Name": "arkcli-feishu-channel",
63
+ "Provider": "feishu",
64
+ "Enabled": true,
65
+ "FeishuApp": {"AppId": "<app-id>"},
66
+ "Policy": {
67
+ "Identity": {"Group": "bot", "P2P": "bot"},
68
+ "Group": {"Trigger": "mention", "ReplyMode": "thread"},
69
+ "Context": {"Enabled": true},
70
+ "Display": {"StreamFinalAnswer": true, "ShowToolCalls": false}
71
+ },
72
+ "SessionConfig": {
73
+ "Agent": {"Id": "<agent-id>", "VersionMode": "latest"},
74
+ "EnvironmentId": "<env-id>",
75
+ "MemoryIds": [],
76
+ "VaultIds": []
77
+ }
78
+ }
79
+ ```
80
+
81
+ ```bash
82
+ ARKCLI_NO_UPDATE_NOTIFIER=1 ARKCLI_CALLER_TYPE=ai_agent ARKCLI_CALLER_NAME=codex ARKCLI_SKILL_NAME=arkcli-agent arkcli agent channel create --file ./channel.json --app-secret-env FEISHU_APP_SECRET --dry-run --format json
83
+ ```
84
+
85
+ `FEISHU_APP_SECRET` 由用户在安全环境预置,不输出它。用户确认实际接入飞书后才去掉 dry-run。SessionConfig.Agent.VersionMode 为 latest 时省略 Version;pinned 时使用已核实的正整数 Version。MemoryIds/VaultIds 空数组表示不绑定;SessionConfig 是整体替换,更新应提交完整对象。Policy 中显式提供的子对象也是完整替换,不把局部字段当深层合并。
86
+
87
+ update/delete/已保存的 validate/app config 接受 `--config-version`。省略时 CLI 仅 GetChannel 一次补当前 ConfigVersion;冲突保留错误,不自动刷新后重试。dry-run 会展示依赖查询和占位版本,不实际调用。
88
+
89
+ 凭证 Valid 不表示机器人已连通:分别检查 Validation.Credential 和 Validation.Connection,再让用户从飞书发一条测试消息并回查关联 Session。Enabled=true 也不等于验证通过。失败时保留错误码和当前版本,不反复重建机器人。
90
+
91
+ 注册返回 pending/succeeded/denied/expired/failed;仅 succeeded 表示授权完成。AppSecret、EncryptKey、VerificationToken 默认脱敏,成功凭证需要用户授权后用 status/config 的 `--output` 保存至新的 0600 文件,不能覆盖现有文件或把文件正文贴到对话。注册凭证有有效期,不承诺过期后可重复获取。
92
+
93
+ 用户打开授权页后,按返回的 PollInterval 主动轮询 `app status`,无需等用户再次说“完成了”;以 ExpireIn 为截止时间,遇到 succeeded/denied/expired/failed 停止。pending 时不重复注册;过期或拒绝后先向用户说明,不自动重新申请授权。
94
+
95
+ ### 已创建但连接失败:手动配置与复验
96
+
97
+ CLI 在 Connection=failed 或获取应用配置时增加顶层 `Guidance`,包含下一步命令;后端 `Result` 和错误码保持原样。退出码 0 只说明本次 API 调用成功,不代表飞书消息链路已接通。保留已有 Channel ID,不重新创建应用或 Channel。
98
+
99
+ 1. 沿用创建时的 profile、环境,执行 `agent channel app config <id> --output ./channel-config.private.json`。文件必须是新路径,完整配置仅保存在本地私密文件中。
100
+ 2. 打开对应应用的“事件与回调”,先核对安全配置,再配置地址。字段对应如下:
101
+
102
+ | 飞书页面配置 | 导出文件字段 |
103
+ | --- | --- |
104
+ | Encrypt Key | `Result.FeishuConfig.EncryptKey` |
105
+ | Verification Token | `Result.FeishuConfig.VerificationToken` |
106
+ | 事件订阅:发送到开发者服务器 | `Result.FeishuConfig.EventRequestUrl` |
107
+ | 回调配置:发送到开发者服务器 | `Result.FeishuConfig.CallbackRequestUrl` |
108
+
109
+ 3. 按页面可编辑项完成配置;不把默认脱敏输出中的 `[REDACTED]` 当真实值。宿主要求人工填写敏感字段时,把这一步交给用户;不要把文件正文、EncryptKey 或 VerificationToken 发到对话中。按页面要求保存、发布。
110
+ 4. 执行 `agent channel validate --id <id>`,分别查看 Credential 和 Connection。仍失败时保留错误码、RequestId 和当前版本,不能声称已连通。最后从飞书发送测试消息,执行 `agent channel sessions list <id>`,核实对应 Session 和回复。
111
+
112
+ 自动配置报 `app_config_permission_denied`、缺少 `application:application:patch` 时,不要求用户反复搜索一个可能未对其开放的同名权限;可尝试上述手动配置。页面提示“Challenge code 没有返回”表示地址校验未通过,需核对安全参数、地址及服务端响应;仅凭该提示不能断定是密钥错误,也不要通过重复创建 Channel 解决。
113
+
114
+ 不实现未公开的 ResetMapping、Retry 或内部文件投递策略命令;不调用飞书内部 API 绕过服务端权限。
115
+
39
116
  ## 当前 Gap
40
117
 
41
118
  - PRD 中 `arkcli +new-agent "..."` 的 CLI 内置 LLM draft + confirm 未实现;当前由调用 arkcli 的 AI agent 负责自然语言理解、模型/skill/tools 选择,再调用结构化 `+new-agent` 或 `agent agent create`。
@@ -71,7 +71,7 @@ arkcli agent env create \
71
71
 
72
72
  override 模型运行参数前,按[模型参数 metadata](model-config.md)查询目标模型;切换模型需重新查询,不自动注入默认值。
73
73
 
74
- Session 创建可以对已有 Agent / Environment 做一次性配置覆盖。override 内的 `System`、`Tools`、`McpServers`、`Skills`、`Multiagent` 和 Environment `Config` 是服务端定义的替换语义,非 nil 字段不会与基 Agent 自动合并;传数组时要传完整数组。
74
+ Session 创建可以对已有 Agent / Environment 做一次性配置覆盖。override 内的 `System`、`Tools`、`McpServers`、`Skills` 和 Environment `Config` 是服务端定义的替换语义,非 nil 字段不会与基 Agent 自动合并;传数组时要传完整数组。`Multiagent` 按字段是否出现区分省略、`null` 和空数组,不能一概当作整对象替换;具体配置和语义见 [Multiagent](agent.md)。
75
75
 
76
76
  ```bash
77
77
  arkcli agent session create \
@@ -88,25 +88,26 @@ arkcli agent session create \
88
88
 
89
89
  上述模型结构归一化同时适用于 `--agent-overrides`、`--agent-overrides @file` 以及通用 `session create --file` 内的 `AgentWithOverrides`。显式空值 `--agent-overrides=` / `--environment-overrides=` 是无效输入,CLI 返回 validation error,不创建 Session。
90
90
 
91
- ### Environment 状态筛选
91
+ ### 归档(火山)
92
92
 
93
- 当前 `arkcli agent env list` **没有注册 `--status`**,不要生成下面这种命令:
93
+ `agent agent archive <agent-id>`、`agent env archive <env-id>`、`agent session archive <session-id>` 是不可逆归档,不是删除,也不自动中断任务。先 get 核对目标,再取得用户对归档的明确确认,才加 `--yes`。不要因为归档失败自动改用 delete 或 interrupt;没有恢复命令。
94
94
 
95
95
  ```bash
96
- arkcli agent env list --status active
96
+ ARKCLI_NO_UPDATE_NOTIFIER=1 ARKCLI_CALLER_TYPE=ai_agent ARKCLI_CALLER_NAME=codex ARKCLI_SKILL_NAME=arkcli-agent arkcli agent session archive <session-id> --dry-run --format json
97
+ ARKCLI_NO_UPDATE_NOTIFIER=1 ARKCLI_CALLER_TYPE=ai_agent ARKCLI_CALLER_NAME=codex ARKCLI_SKILL_NAME=arkcli-agent arkcli agent session archive <session-id> --yes --format json
97
98
  ```
98
99
 
99
- `ListEnvironments` 后端请求也没有 `Status` 过滤字段;返回的 Environment 对象只有可选的 `ArchiveTime`。需要按状态找环境时,先拉全量,再由调用 arkcli 的 AI Agent 本地筛选:
100
+ Agent 归档不产生新版本,保留历史配置;Environment 归档不删除数据。已有 Session 的行为以服务端为准,不承诺停止运行或释放费用。Session 归档要求满足后端状态前提,运行中拒绝时先汇报,不能擅自结束用户任务。
101
+
102
+ 火山三类 `list` 默认排除归档资源,查询归档资源必须带 `--include-archived`。Agent / Environment 另支持 `--status active` 或 `--status terminated`,可重复;只查归档资源时同时传 `--include-archived --status terminated`。单独传 `--status terminated` 不会自动包含归档资源,空结果不能据此判断没有归档资源。这里 `terminated` 是后端归档筛选值,不写成 `archived`。Session `--status` 仍使用它原有的运行状态枚举,不套用 Agent/Env 枚举。
100
103
 
101
104
  ```bash
102
- arkcli agent env list --page-all --format json
105
+ ARKCLI_NO_UPDATE_NOTIFIER=1 ARKCLI_CALLER_TYPE=ai_agent ARKCLI_CALLER_NAME=codex ARKCLI_SKILL_NAME=arkcli-agent arkcli agent env list --include-archived --page-all --format json
106
+ ARKCLI_NO_UPDATE_NOTIFIER=1 ARKCLI_CALLER_TYPE=ai_agent ARKCLI_CALLER_NAME=codex ARKCLI_SKILL_NAME=arkcli-agent arkcli agent agent list --include-archived --status terminated --page-all --format json
107
+ ARKCLI_NO_UPDATE_NOTIFIER=1 ARKCLI_CALLER_TYPE=ai_agent ARKCLI_CALLER_NAME=codex ARKCLI_SKILL_NAME=arkcli-agent arkcli agent env list --include-archived --status terminated --page-all --format json
103
108
  ```
104
109
 
105
- - `ArchiveTime` 非空:`archived`
106
- - `ArchiveTime` 为空或字段缺失:`active`
107
- - 前端领域类型虽然预留了 `updating`,但当前返回契约没有可可靠推导它的字段;不要声称支持 `updating` 筛选。
108
- - 不要只过滤默认第一页;状态筛选必须配合 `--page-all`,并关注全局 `--page-limit` 是否导致结果仍被截断。
109
- - env `--page-all` 默认使用 `Limit=100`,并把每页响应的 `NextPage` 作为下一次请求的 `Page`;`--page-limit` 限制的是最多请求页数,不是结果条数。
110
+ 看实际 `ArchiveTime` / `Status` 判断归档结果;旧响应缺字段不推断为已经归档。若服务端版本尚不支持 Status,不把空结果当作“没有归档资源”。`--page-limit` 是最多请求页数,达到上限后检查 NextPage。BytePlus 不新增上述 flags/命令,继续使用旧查询方式。
110
111
 
111
112
  ## Files 与 Session Resources
112
113
 
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: arkcli-helper
3
3
  version: 1.1.5
4
- description: "arkcli helper:为 Claude Code / Codex / OpenCode / OpenClaw / Hermes / ZCode 配置火山方舟 Plan 或 Platform Endpoint 的 model/provider,或给支持的 Agent(含 MCP-only Trae)配置 Harness 工具。真人 TTY 运行 `arkcli helper` 可选择模型和 Harness 能力;`helper mcp` 默认保持整组 Agent Plan MCP 行为,传 `--capability datapro|web-search|agent-memory` 只配单项,传 `--capability cua` 只给目标 Agent 安装云电脑 Skill;连 model/provider 一起配置用 `helper configure`,查状态用 `helper list`,移除用 `helper reset`。Agent Plan / Team 还支持专业数据集、豆包搜索、Agent 记忆、AI Native 应用开发底座、Agent 进化与 routing.v1 强制检索路由;上下文出现 ARKCLI ROUTING ENFORCEMENT / routing.v1,或用户要求在豆包搜索、DataPro、OpenViking、Supabase 之间强制分流时也使用本 Skill:调用这四类受管 Provider 前先提交 Route Plan,再调用唯一授权 Provider;原生 WebSearch/WebFetch/WebExtract 位于路由管理范围之外。Platform 只允许本人创建、Running、已验证为文本输出的 Endpoint,不配置 MCP、Supabase 或强制路由。豆包搜索配置成功后默认关闭目标客户端原生 WebSearch;传 `--keep-native-websearch` 可保留,并可用 `helper reset` 完整恢复 ArkCLI 配置。"
4
+ description: "arkcli helper:为 Claude Code / Codex / OpenCode / OpenClaw / Hermes / ZCode 等本机 Agent 配置火山方舟 Plan 或 Platform Endpoint 的 model/provider。真人 TTY 运行 `arkcli helper` 可选择模型和 Harness 能力;`helper mcp` 默认保持整组 Agent Plan MCP 行为,传 `--capability datapro|web-search|agent-memory` 只配单项,传 `--capability cua` 只给目标 Agent 安装云电脑 Skill;连 model/provider 一起配置用 `helper configure`,查安装/配置状态用 `helper list` 或 `helper status`,移除用 `helper reset`。Agent Plan / Team 还支持专业数据集、豆包搜索、Agent 记忆、AI Native 应用开发底座、Agent 进化与 routing.v1 强制检索路由;上下文出现 ARKCLI ROUTING ENFORCEMENT / routing.v1,或用户要求在豆包搜索、DataPro、OpenViking、Supabase 之间强制分流时也使用本 Skill:调用这四类受管 Provider 前先提交 Route Plan,再调用唯一授权 Provider;原生 WebSearch/WebFetch/WebExtract 位于路由管理范围之外。Platform 只允许本人创建、Running、已验证为文本输出的 Endpoint,不配置 MCP、Supabase 或强制路由。豆包搜索配置成功后默认关闭目标客户端原生 WebSearch;传 `--keep-native-websearch` 可保留,并可用 `helper reset` 完整恢复 ArkCLI 配置。"
5
5
  metadata:
6
6
  requires:
7
7
  bins: ["arkcli"]
8
- cliHelp: "arkcli helper mcp --help"
8
+ cliHelp: "arkcli helper --help"
9
9
  ---
10
10
 
11
11
  # arkcli helper —— 给本机 AI Agent 配置 Plan / Platform Endpoint / 注入 MCP
@@ -23,12 +23,13 @@ metadata:
23
23
  - 普通 Helper 准入从 `arkcli helper list` 和用户指定的目标开始;不要为补齐上下文自动执行 `profile show/list/keys list`。这些 Profile 命令可能在线同步并回写 Key,只有用户显式要求 Profile 管理时才进入,并先说明影响。
24
24
  - 用户要查看或配置 Agent 的 model/provider、Plan、Platform Endpoint,或核对 `--with-mcp` / `--with-supabase` / `--with-routing` 等非交互选项时,必须选择 `arkcli helper configure`;只查看用法也要运行 `arkcli helper configure --help`,不能退化成父级 `arkcli helper --help`。
25
25
  - 用户只要 Harness 工具、不改 model/provider 时,选择 `arkcli helper mcp [target]`。不传 `--capability` 配整组 Agent Plan MCP;只要专业数据集、豆包搜索或 Agent 记忆时分别传 `--capability datapro|web-search|agent-memory`;只要云电脑时传 `--capability cua`。选择豆包搜索后默认关闭目标客户端的原生 `WebSearch/web_search`,用户要求保留时加 `--keep-native-websearch`。发生关闭时立即输出作用域、配置文件和完整 reset 命令。只查看用法时运行 `arkcli helper mcp --help`。
26
+ - 用户只想确认某个 Agent 是否安装、是否已被 arkcli 配置、配置文件权限是否安全时,选择 `arkcli helper status <harness>`;它只读本机文件,不读账号、不写配置。
26
27
  - Helper 配置 Agent Plan 时只能使用该 profile 的专属/席位 Key,不能用普通 API Key 池兜底。个人版专属记录存在但非 Active(如 `Restricted`)时,真人 TTY 会先说明轮转将立即使旧 Key 失效并询问;确认后只轮转一次、最多读 3 次状态,第一轮 Active 即停止。无专属记录、用户拒绝或非 TTY 时不轮转;失败引导必须去 Agent Plan 使用配置页,不能去普通 API Key 页面或 `auth apikey`。
27
28
  - `arkcli-auth` 只处理实际认证阻塞。用户仅要求查看 helper 的 `--help` 时,不要转去登录、`init-volc` 或其他认证命令。
28
29
 
29
30
  ## 适用场景 / 唤起信号
30
31
 
31
- - 用户要给本机 Claude Code / Codex / OpenCode / OpenClaw / Hermes / ZCode 配置 Plan 或 Platform Endpoint 的 model/provider。
32
+ - 用户要给本机 Claude Code / Codex / OpenCode / OpenClaw / Hermes / ZCode / KimiCode / Grok / WorkBuddy 配置 Plan 或 Platform Endpoint 的 model/provider。
32
33
  - 用户要给支持的目标 Agent 配置豆包搜索、专业数据集或 OpenViking MCP,只安装云电脑 CUA Skill,或配置 byted-supabase。
33
34
  - 用户询问 `arkcli helper` 的安装态、配置态、文件落点、重载方式或 Agent Plan Harness 抵扣/超额后付费矩阵。
34
35
 
@@ -152,6 +153,7 @@ arkcli helper configure codex \
152
153
  → 用户在 prompt 里**点名了某个 agent**(如"给 opencode / codex 配"):跑 `arkcli helper mcp opencode` / `arkcli helper mcp codex`
153
154
  → 用户说"**当前 / 这个 Agent**"或没点名:跑 `arkcli helper mcp`(自动检测当前 host)
154
155
 
156
+
155
157
  ## 子命令穷举
156
158
 
157
159
  | 调用 | 说明 |
@@ -159,10 +161,13 @@ arkcli helper configure codex \
159
161
  | `arkcli helper mcp [target] [--capability <datapro\|web-search\|agent-memory\|cua>] [--profile P] [--ov-resource <库名>] [--scope project] [--keep-native-websearch] [--codex-config-scope profile\|global] [--codex-profile <name>] [--dsh-config-scope home\|profile] [--dsh-profile <name>]` | 不传 `--capability` 保持整组 MCP 旧行为;显式选择时只配一项,**不改 model**。`web-search` 还会安装 Skill 并按原规则处理原生 WebSearch;`agent-memory` 仅个人版,多库用 `--ov-resource`;`cua` 仅个人版 Medium/Large/Max,只给 target 安装 `byted-util-ark-cua` Skill,不写任何 MCP;Codex 的 MCP 默认写 profile `~/.codex/arkcli.config.toml`;DSH 默认写 home 层,profile 层需同时指定两个 DSH flag |
160
162
  | `arkcli helper configure <harness> [--profile P] [--model M\|--endpoint ep-id] [--with-mcp] [--keep-native-websearch] [--with-supabase] [--with-routing] [--codex-config-scope profile\|global] [--codex-profile <name>]` | Plan 用 model/provider;Platform 必须用 `--endpoint` 选择文本 Endpoint。仅 Plan 可加 MCP/Supabase;强制路由仅 Agent Plan 可用。`--keep-native-websearch` 只影响豆包搜索配置,不改变路由 gate。 |
161
163
  | `arkcli helper list` | 查支持的 agent + 安装/配置状态(只读) |
164
+ | `arkcli helper status <harness>` | 只读查看单个 harness 的安装态、arkcli 配置态、关键文件权限/大小与已注入 MCP server |
162
165
  | `arkcli helper supabase [--profile P]` | **非 MCP**:装 byted-supabase-cli + skill + 注入火山登录态(打通 byted-supabase 数据库能力);跟 harness 无关。仅 Agent Plan(个人版全档 + 团队版全档) |
163
166
  | `arkcli helper reset <harness>` | 完整移除 arkcli 注入的 model/provider/MCP/托管路由 hook/tool/plugin,并恢复 ArkCLI 拥有且未被外部修改的原生搜索字段 |
164
167
  | `arkcli helper` | TTY 交互向导(需终端;非交互场景改用上面的);进入向导前会检查登录态,未登录/SSO 过期时按当前登录上下文拉起 SSO(火山走 volc-sso;全新用户无明确上下文时走 auth login 菜单),成功后继续向导;Agent Plan/Team 按 profile→model→Agent→能力多选→逐项配置推进,随后只基于已验真的真实 Provider 动态确认强制路由 |
165
168
 
169
+ `configure` / `mcp` / `reset` / 交互向导以**整条命令**为本地文件事务:成功保留全部写入;任一步失败自动回滚本命令写过的配置(含 Skill 凭证),并保留原错误、追加回滚提示。Agent 安装与 `npx` 下载等外部副作用不在回滚范围。非 human 输出成功时带 `transaction: {status, files, paths}`(`paths` 是本命令涉及的全部本地文件);详见 [`references/arkcli-helper.md`](references/arkcli-helper.md)。
170
+
166
171
  > ⚠️ 想"只加 MCP" → `helper mcp`;想"把 agent 接到 plan、连模型一起" → `helper configure --with-mcp`。别用 `configure` 去只加 MCP(它会一并(重)写 model)。
167
172
  >
168
173
  > 🎯 用户说"**把(我 plan 的)全套 harness 工具都配上 / 都给我 set 好**"(MCP + Supabase 一次到位)→ `arkcli helper configure <harness> --with-mcp --with-supabase`。这是 agent 唯一能一条命令配齐 MCP 三件套 + Supabase 的路径(交互向导 `arkcli helper` 要 TTY、agent 跑不了;它的自动 SSO 只服务真人终端);`--with-mcp` 只配 MCP、不含 Supabase,想带 Supabase **必须显式加 `--with-supabase`**(资格不够 / 失败只 warn,不阻断 harness 配置)。
@@ -181,9 +186,9 @@ arkcli helper configure codex \
181
186
 
182
187
  ## 范围边界(管好,别越界)
183
188
 
184
- - **model/provider 可配置 target**:`claude-code` / `codex` / `deepseek-harness` / `pi` / `opencode` / `openclaw` / `hermes` / `zcode` / `workbuddy`。其中 Hermes 与 Pi 支持 Plan 和 Platform Endpoint,但都不支持 MCP;DSH 支持 Plan / Platform / Coding Plan 与 MCP 注入;ZCode 与 WorkBuddy 支持 model + MCP。
185
- - **可注入 MCP 的 target 有 8 个**:`claude-code` / `codex` / `opencode` / `openclaw` / `trae` / `deepseek-harness` / `zcode` / `workbuddy`。CUA 是 Skill 而非 MCP,还可精确安装给 `hermes` / `pi`;命令只传单个 target,不扫描或改动其他 Agent。
186
- - 本 skill 会被 `arkcli +connect` 装进很多 agent(cursor / gemini-cli / codex …40+),但 **MCP 注入只支持上一条列出的 8 个 target**。host 是其它 agent 时:要么用户点名其一作 target,要么命令会报"请显式指定" —— **绝不静默配错对象**。
189
+ - **model/provider 可配置 target**:`claude-code` / `codex` / `deepseek-harness` / `pi` / `opencode` / `openclaw` / `hermes` / `zcode` / `kimi-code` / `grok` / `workbuddy`。其中 Hermes 与 Pi 支持 Plan 和 Platform Endpoint,但都不支持 MCP;DSH 支持 Plan / Platform / Coding Plan 与 MCP 注入;ZCode、KimiCode、Grok 与 WorkBuddy 支持 model + MCP。Cursor 与 Trae 是 MCP-only,不支持 `helper configure`。
190
+ - **可注入 MCP 的 target 有 11 个**:`claude-code` / `codex` / `opencode` / `openclaw` / `trae` / `deepseek-harness` / `zcode` / `kimi-code` / `cursor` / `grok` / `workbuddy`。CUA 是 Skill 而非 MCP,还可精确安装给 `hermes` / `pi`;命令只传单个 target,不扫描或改动其他 Agent。
191
+ - 本 skill 会被 `arkcli +connect` 装进很多 agent(cursor / gemini-cli / codex …40+),但 **MCP 注入只支持上一条列出的 11 个 target**。host 是其它 agent 时:要么用户点名其一作 target,要么命令会报"请显式指定" —— **绝不静默配错对象**。
187
192
  - `codex` 支持 model/provider + MCP。默认 **profile 模式**写 `~/.codex/arkcli.config.toml`,需用 `codex --profile arkcli` 启动 terminal/TUI 才生效;传 `--codex-config-scope global` 才写 `~/.codex/config.toml`,该范围可能被 Codex CLI/TUI、Codex App、IDE extension 共享读取。
188
193
  - `trae`(AI IDE)是 MCP-only:不配 model/provider;**无运行态宿主检测**(不会被自动当成 host),只能显式 `arkcli helper mcp trae`。默认写用户级 `~/.trae/mcp.json`,加 `--scope project` 写项目级 `./.trae/mcp.json`(项目级需在 Trae「设置 → MCP」开启「启用项目级 MCP」开关 + 重开项目)。豆包搜索成功后另写项目根 `.trae/hooks.json`,还需在 `TRAE Settings > Hooks` 启用当前项目。
189
194
  - `hermes` 支持 Plan / Platform Endpoint 的 model/provider 配置,但暂不支持 MCP 注入 → MCP 请求命中就直说"暂不支持"。
@@ -196,7 +201,10 @@ arkcli helper configure codex \
196
201
 
197
202
  ## 前提
198
203
 
199
- - **必须有 Agent Plan 订阅**(豆包搜索 / dataPro 要 Agent Plan 的 key;OpenViking 两台是个人版专属)。命令自动定位账号下的 Agent Plan profile,**与当前 active profile 无关**;个人版 `agent-plan` 与团队版 `agent-plan-team` 都能注入,但**两者不等价**:个人版注入四台,**团队版 `agent-plan-team` 与 OpenViking 无关,只注入豆包搜索 + dataPro 两台**。没有就引导 `arkcli auth login` 开通;账号同时有多个 Agent Plan profile(如个人版 + 团队版)时,命令会列出本次检测到的 profile name;使用宿主提供的结构化选择能力让用户选一个,选定后带 `--profile <name>` 重跑,不得擅自偏向个人版、团队版或 active profile。
204
+ - **必须有受支持的 Plan 订阅**(`agent-plan` / `agent-plan-team` / `coding-plan` / `coding-plan-team`,具体取决于当前产品与套餐)。
205
+ - `helper configure` 使用 `--profile` 指定 profile;未指定时使用当前 active profile,**不会**在账号里自动挑 Agent Plan。profile 类型不支持时 fail-fast。
206
+ - `helper mcp` 相反:它必须定位 Agent Plan profile,**与当前 active profile 无关**。个人版 `agent-plan` 与团队版 `agent-plan-team` 都能注入 MCP,但**两者不等价**:个人版注入四台,团队版 `agent-plan-team` 与 OpenViking 无关,只注入豆包搜索 + dataPro 两台。账号同时有多个 Agent Plan profile 时,命令会列出本次检测到的 profile name;使用宿主提供的结构化选择能力让用户选一个,选定后带 `--profile <name>` 重跑,不得擅自偏向个人版、团队版或 active profile。
207
+ - 没有可用订阅时,引导 `arkcli auth login` 开通。
200
208
  - 注入后 **agent 需重启**才会加载新 MCP。Codex profile 模式还需用 `codex --profile <name>` 启动;Trae 还需去「设置 → MCP」面板确认 MCP 已启用(项目级文件额外要开「启用项目级 MCP」开关),并在 `Settings > Hooks` 启用当前项目后重开项目。
201
209
 
202
210
  ## OpenViking 库的选择(openviking-dataplane 专属;**仅个人版 agent-plan**)
@@ -211,11 +219,13 @@ arkcli helper configure codex \
211
219
  - 取 key 失败(非 0 库)→ openviking-dataplane 写占位符 `Bearer <OPENVIKING_KEY>`,提示用户手动替换。
212
220
  - `openviking-controlplane` 不受上述影响:个人版只要有 Agent Plan 就始终注入(团队版不注入,见上)。
213
221
 
222
+
214
223
  ## 路由判断 / 反触发
215
224
 
216
225
  - "给 Agent 配 MCP / 豆包搜索 / 联网搜索 / dataPro / web search" → `arkcli helper mcp`
217
226
  - "只给 Codex 配某一项 Harness 能力" → `arkcli helper mcp codex --capability <datapro|web-search|agent-memory>`;只配云电脑 → `arkcli helper mcp codex --capability cua`
218
227
  - "把 agent 指向我的 plan(连模型一起)" → `arkcli helper configure`
228
+ - "看看某个 Agent 现在有没有装好 / 配置好 / 文件权限是否安全" → `arkcli helper status <harness>`
219
229
  - "打开 helper 看 Harness 抵扣/超额开关和本地配置矩阵" → 真人 TTY 运行 `arkcli helper`;Agent 不自动驾驶该菜单
220
230
  - "把全套 harness 工具都配上 / 一次配齐 MCP + Supabase" → `arkcli helper configure <h> --with-mcp --with-supabase`
221
231
  - "启用强制受管 Provider 路由 / routing.v1 / 防止豆包搜索、DataPro、OpenViking、Supabase 串路由" → 使用本 Skill 的强制检索路由协议,执行 `arkcli helper configure <h> --with-routing`
@@ -16,10 +16,34 @@
16
16
  [`../../arkcli-plans/references/arkcli-plans-agreement-signing.md`](../../arkcli-plans/references/arkcli-plans-agreement-signing.md)。
17
17
 
18
18
  执行 `configure/reset/mcp/supabase` 前,Agent 必须展示准确 target、
19
- profile、scope 与文件落点并取得确认;只能用 `helper list` 做只读检查。
19
+ profile、scope 与文件落点并取得确认;只能用 `helper list` / `helper status` 做只读检查。
20
20
  不要生成 `arkcli --dry-run helper ...` 或
21
21
  `arkcli helper ... --dry-run`。
22
22
 
23
+ ## IPC / Pipe 调用契约
24
+
25
+ Helper 作为第三方 Agent 的本地能力入口时,按进程契约消费,不要解析人类可读表格:
26
+
27
+ - **成功**:业务 JSON 只写 stdout,进程退出码 `0`;进度/提示写 stderr,不得混入 stdout。
28
+ - **失败**:错误信封只写 stderr,stdout 保持为空。信封固定为
29
+ `{"ok": false, "error": {"type": "...", "message": "...", "trace_id": "..."}}`。
30
+ 退出码按错误类别:`1` 一般错误、`2` 参数/资格校验、`3` 认证、`4` 网络、`5` 服务端 API。
31
+ - 调用方必须同时捕获 stdout 与 stderr;只读 stdout 会把失败误判为“无输出”。
32
+ - 只读探测(`helper list` / `helper status`)不联网、不刷新凭证、不写文件;
33
+ 写命令(`configure` / `mcp` / `reset` / `setup`)成功后附带
34
+ `transaction: {"status": "committed", "files": <n>, "paths": [...]}`。
35
+ - `transaction.paths[]` 是本命令实际改写/删除过的全部本地文件(按首次写入顺序),
36
+ `transaction.files` 是同一集合的数量。MCP 注入、shell rc、Skill 凭证等
37
+ 非 configurator 主配置的写入也包含在这里,是 IPC 调用方判断“哪些文件变了”的
38
+ 权威来源。
39
+ - 成功 JSON 的 `files[]` 是 configurator 主配置落点(模型/provider,以及 MCP-only
40
+ host 的主文件);`helper mcp` 不返回 `files[]`,用 `mcp_servers[]` +
41
+ `transaction.paths[]`。不要把 `files[]` 当成完整写入集合。
42
+ - 非交互调用必须显式传 target;账号存在多个 Agent Plan profile 时必须显式传
43
+ `--profile`。不要依赖宿主环境变量探测,也不要依赖 TTY 交互。
44
+ - 写命令失败时,本次命令已写入的本地配置按事务回滚;错误消息会追加回滚结果
45
+ (含回滚失败的文件)。调用方应把 `ok=false` 视为“可能已回滚”,不要假设部分配置已生效。
46
+
23
47
  ## `arkcli helper mcp [target]`
24
48
 
25
49
  这是**不改 model / provider / base_url**的非交互 Harness 工具入口。不传 `--capability` 时完全保持存量行为:**个人版 `agent-plan` 四台 MCP**(豆包搜索 + DataPro + OpenViking 数据面/控制面),**团队版 `agent-plan-team` 两台 MCP**(豆包搜索 + DataPro)。传 `--capability` 时只配所选单项,不带入其他已开启工具。
@@ -132,6 +156,9 @@ openviking-dataplane 的 `Authorization: Bearer <key>` 绑定到具体 OpenVikin
132
156
  | trae | 默认 `~/.trae/mcp.json`(`mcpServers.*`,与 claude 同构);`--scope project` → `./.trae/mcp.json` | 全局:去「设置 → MCP」确认 MCP 已启用 + 重启;项目级:开「启用项目级 MCP」开关 + 重开项目 |
133
157
  | deepseek-harness | 默认 `$DSH_HOME/profiles/<name>/cordis.patch.yml`(`--dsh-profile <name>` 必填);`--dsh-config-scope home` → `$DSH_HOME/cordis.patch.yml` | 重启 `dsh --profile <name>`(profile scope);home 层全局生效 |
134
158
  | zcode | `$ZCODE_HOME/cli/config.json`(默认 `~/.zcode/cli/config.json`,`mcp.servers.*`);model/provider 在 `$ZCODE_HOME/v2/config.json` | 完全退出 ZCode 主进程后重新打开并新建会话;旧会话不会热加载 provider 配置 |
159
+ | kimi-code | `$KIMI_CODE_HOME/mcp.json`(默认 `~/.kimi-code/mcp.json`);model/provider 在 `$KIMI_CODE_HOME/config.toml` | 重启 KimiCode |
160
+ | cursor | `~/.cursor/mcp.json`(`mcpServers.*`,MCP-only) | 重启 Cursor / 重载 MCP |
161
+ | grok | `$GROK_HOME/mcp.json`(默认 `~/.grok/mcp.json`);model/provider 在 `$GROK_HOME/config.toml` | 重启 Grok |
135
162
  | workbuddy | 同时写 `~/.workbuddy-ai/mcp.json`、`~/.workbuddy/mcp.json` 与 `~/.codebuddy/mcp.json`(`mcpServers.*`,与 claude 同构);model 清单写各自 `models.json`(OpenAI 兼容,arkcli 项打 `arkcliManaged` marker) | 重启 CodeBuddy IDE |
136
163
 
137
164
  ### 原生 WebSearch 的选择与精确落点
@@ -152,7 +179,7 @@ TTY 配置豆包搜索时,在 MCP 与 Skill 都成功后展示“关闭原生
152
179
 
153
180
  触发条件:只有豆包搜索被选择、MCP/Skill 配置成功且用户未选择保留时才写上述配置。普通 `helper configure`、Platform/Coding Plan、选择跳过豆包搜索、MCP 注入失败或传 `--keep-native-websearch` 都保持原路径不变。若关闭原生搜索失败,命令明确输出“豆包搜索已配置,但原生搜索关闭失败”,不得把部分成功包装成全部成功。
154
181
 
155
- ### ZCode 模型 limit 与网关边界
182
+ ## ZCode 模型 limit 与网关边界
156
183
 
157
184
  `helper configure zcode` 写 `$ZCODE_HOME/v2/config.json`(默认
158
185
  `~/.zcode/v2/config.json`)。Plan 模型的 `limit` 优先来自套餐模型接口的
@@ -183,6 +210,67 @@ ArkCLI 重新执行原 `arkcli helper configure zcode --profile ... --model ...`
183
210
  ZCode 主进程、重新打开并新建会话;只切换模型或继续使用旧会话不会热加载 provider
184
211
  配置。不要把 `limit.context` 一并改成十进制,也不要长期手改生成配置。
185
212
 
213
+ ## `arkcli helper status <harness>`
214
+
215
+ 这是面向 Agent / IPC / Pipe 调用方的**只读体检入口**:只读本机文件,不读账号、
216
+ 不刷新凭证、不联网、不写文件、不触发安装或子进程。
217
+
218
+ ```bash
219
+ arkcli helper status <harness>
220
+ ```
221
+
222
+ 人类可读输出是一行表格(`HARNESS / INSTALLED / CONFIGURED / MODEL / MCP / SEARCH /
223
+ SETTINGS`)。`--format json` 返回稳定字段:
224
+
225
+ | 字段 | 语义 |
226
+ |---|---|
227
+ | `harness` / `display_name` | 稳定 harness ID 与展示名 |
228
+ | `installed` | 按 `detect_command` 在 PATH 上探测到的结果 |
229
+ | `installed_known` | 是否存在可靠探测命令;`false` 时 `installed` 无意义(Trae / WorkBuddy / DSH 等无 CLI 或推荐 npx 运行) |
230
+ | `detect_command` | 实际用于探测的命令;空表示不探测 |
231
+ | `configured` | 是否检测到 ArkCLI 托管的配置标记(model/provider 或 MCP) |
232
+ | `supports_model` / `supports_mcp` | 当前**编译产品**与 harness 共同决定的能力 |
233
+ | `native_search_supported` | harness 是否具备 ArkCLI 可管理的原生搜索关闭能力 |
234
+ | `settings_path` / `mcp_path` | 主配置与 MCP 配置落点;不适用时为空 |
235
+ | `files[]` | `path` / `exists` / `mode`(四位八进制)/ `size`;始终返回数组 |
236
+ | `mcp_servers[]` | ArkCLI 内置 MCP server 状态对象数组:`name` / `transport` / `installed` / `key_state`(`real`/`placeholder`/`absent`);`supports_mcp=false` 时为空数组 |
237
+ | `mcp_status_error` | MCP 状态读取失败原因;不能把失败当作“未注入” |
238
+
239
+ 边界:
240
+
241
+ - `configured=false` 只表示没有 ArkCLI 托管标记,不表示 Agent 不能工作。
242
+ - `installed=false && installed_known=true` 才能提示“未安装”;`installed_known=false`
243
+ 时必须提示“无法自动判定”。
244
+ - `files[].mode` 用于发现 `0644` 等过宽权限;凭证文件预期为 `0600`。
245
+ - 该命令不接受 `--dry-run`,也不替代 `configure/reset` 的写前确认。
246
+
247
+ ## 本地写入事务与回滚
248
+
249
+ `helper configure` / `helper mcp` / `helper reset` / 交互向导把**整条命令**视为一个本地文件事务:
250
+
251
+ - 每个文件在第一次被改写或删除前先做内存快照(同一路径只快照一次);
252
+ - 命令成功时提交,所有写入保留;
253
+ - 命令任意一步失败时,按写入逆序恢复所有已改文件、删除本次新建的文件、重建本次删除的文件(保留原权限);
254
+ - 回滚失败不会吞掉原错误:命令仍返回原错误,并追加一条本地化提示,列出未能恢复的文件;
255
+ - 快照失败会拒绝写入,避免留下无法回滚的半套配置。
256
+
257
+ 边界:
258
+
259
+ - 事务只覆盖 ArkCLI 通过统一原子写与受控删除写入的本机配置文件(含 Skill 凭证 `.env`);Agent 安装、`npm` / `npx skills add` 下载、外部 CLI 登录态等外部副作用**不在事务内**,只能 best-effort。
260
+ - DSH 的 `settings.yaml` + `.credentials.yaml` 双文件仍有自己的原子事务;它嵌套在命令级事务内,由命令级事务统一收口。
261
+ - `--dry-run` 不写入,也不开启事务。
262
+
263
+ 非 human 格式下,`configure` / `mcp` / `reset` 成功输出新增:
264
+
265
+ ```json
266
+ "transaction": {"status": "committed", "files": 3, "paths": ["/home/u/.claude/settings.json", "/home/u/.claude.json", "/home/u/.claude/skills/byted-web-search/.env"]}
267
+ ```
268
+
269
+ `files` 是本命令实际快照过的不同路径数;`paths` 是同一集合的完整路径(按首次写入
270
+ 顺序);`0` / `[]` 表示命令成功但没有改写任何本地配置(例如 CUA 只安装外部 Skill)。
271
+ 快照可能包含为回滚而记录、但最终内容未变的文件;调用方以 `paths` 作为“本命令涉及
272
+ 哪些本地文件”的权威集合。
273
+
186
274
  ## 错误与边界 case
187
275
 
188
276
  | 现象 | 原因 | 处理 |
@@ -190,8 +278,8 @@ ZCode 主进程、重新打开并新建会话;只切换模型或继续使用
190
278
  | `未知 --capability` | 传了服务端 HarnessName、MCP server ID 或 `all` | 只用 `datapro` / `web-search` / `agent-memory` / `cua`;要整组时去掉该 flag |
191
279
  | `agent-memory 仅支持 Agent Plan 个人版` | `--profile` 指向 `agent-plan-team` | 换个人版 profile;团队版不含 OpenViking |
192
280
  | `cua 仅支持 Agent Plan 个人版 Medium/Large/Max` | profile 是团队版或个人版 Small | 换合格的个人版 profile,不要改用 `configure --with-cua` 绕过资格闸 |
193
- | `无法确定要配置哪个 agent` | host 不是可检测的 3 个 / 信号冲突 / 无信号(含 Codex / Trae / DSH / ZCode / WorkBuddy 等) | 显式 `arkcli helper mcp <claude-code\|codex\|opencode\|openclaw\|trae\|deepseek-harness\|zcode\|workbuddy>` |
194
- | `<X> 暂不支持 MCP 注入` | target 是 hermes 或未来不支持的 agent | 仅 claude-code/codex/opencode/openclaw/trae/deepseek-harness/zcode/workbuddy 可注入 |
281
+ | `无法确定要配置哪个 agent` | host 不是可检测的 3 个 / 信号冲突 / 无信号(含 Codex / Trae / DSH / ZCode / WorkBuddy 等) | 显式 `arkcli helper mcp <claude-code\|codex\|opencode\|openclaw\|trae\|deepseek-harness\|zcode\|kimi-code\|cursor\|grok\|workbuddy>` |
282
+ | `<X> 暂不支持 MCP 注入` | target 是 hermes / pi 或未来不支持的 agent | 仅 claude-code/codex/opencode/openclaw/trae/deepseek-harness/zcode/kimi-code/cursor/grok/workbuddy 可注入 |
195
283
  | `--scope project 仅 Trae 支持` | 对非 Trae agent 传了 `--scope project` | 去掉 `--scope`(其它 agent 一律用户级全局) |
196
284
  | `--codex-config-scope / --codex-profile 仅 Codex harness 支持` | 对非 Codex agent 传了 Codex 专属 flag | 去掉 Codex flag,或 target 改为 `codex` |
197
285
  | `--dsh-config-scope / --dsh-profile 仅 DeepSeek Harness 支持` | 对非 DSH agent 传了 DSH 专属 flag,或给 `--capability cua` 传了 MCP 配置 flag | 去掉 DSH flag,或对 MCP capability 将 target 改为 `deepseek-harness`;CUA 只安装 Skill,不接受这些 flag |
@@ -206,9 +294,9 @@ ZCode 主进程、重新打开并新建会话;只切换模型或继续使用
206
294
  | TRAE 显示 Hook 文件已写但原生搜索仍可调用 | 项目 Hooks 尚未在 IDE 中启用 | 在 `TRAE Settings > Hooks` 启用当前项目并重开 |
207
295
  | reset 未恢复原生搜索 | 用户原本就已关闭,或配置后同一字段被外部修改 | ArkCLI 不接管原有禁用;冲突时保留用户当前值并输出警告 |
208
296
  | DSH 提示检测到旧版配置或 flat credentials | 旧版 ArkCLI 写入格式与当前 DSH provider / credentials 契约不兼容;flat key 可能单独存在,也可能残留在 version 1 文档顶层 | 先运行 `arkcli helper reset deepseek-harness`,再重新执行 `configure`;不要手工删除 `apiKeyEnv` |
297
+ | ZCode 调用 `glm-5.2` 等模型时报 `InvalidParameter` / token 上限 400 | 旧配置把 ArkModels 的 `131072` 等二进制近似值直接作为 `limit.output` 发给十进制网关 | 升级 ArkCLI 后重跑 `helper configure zcode` 并重启 ZCode;确认 `limit.output=128000`,但保留权威 `limit.context` |
209
298
 
210
299
  DSH model/provider 写入还遵循以下 ownership 规则:`settings.yaml` 使用独立的 `llm-pi-ai.providers.arkcli-<planType>`,凭据使用 `.credentials.yaml` version 1 文档的 `refs.ARKCLI_<PLAN>_API_KEY`,让 DSH credentials service 能按 provider 的 `apiKeyEnv` 解析。两个文件按一个可回滚事务更新。检测到纯 flat credentials、version 1 文档顶层残留的 legacy credential key,或 `llm-deepseek` 同时具有 `apiKeyEnv: DEEPSEEK_API_KEY` 与精确 Ark 数据面 HTTPS URL 的旧 ArkCLI 指纹时,`configure` fail-fast,不做隐式迁移,并明确要求先运行 `arkcli helper reset deepseek-harness`;该 reset 兼容读取旧格式并清理旧 ArkCLI 内容。不要把自定义 `apiKeyEnv` 当成 ArkCLI ownership。`helper reset deepseek-harness` 仅移除 fingerprint 仍完整匹配的 provider、对应凭据以及仍指向该 provider 的 `agent-default-model`。
211
- | ZCode 调用 `glm-5.2` 等模型时报 `InvalidParameter` / token 上限 400 | 旧配置把 ArkModels 的 `131072` 等二进制近似值直接作为 `limit.output` 发给十进制网关 | 升级 ArkCLI 后重跑 `helper configure zcode` 并重启 ZCode;确认 `limit.output=128000`,但保留权威 `limit.context` |
212
300
 
213
301
  ## Platform Endpoint 配置
214
302
 
@@ -23,7 +23,7 @@
23
23
 
24
24
  - 仅查询套餐持有、购买、续费或席位列表时转 `arkcli-plans`。
25
25
  - 仅查询模型目录或能力推荐时转 `arkcli-models`。
26
- - Agent 自动化不得尝试发送按键操纵 `arkcli helper` TTY 菜单;应选择 `helper configure/mcp/supabase/list/reset` 的最具体子命令。
26
+ - Agent 自动化不得尝试发送按键操纵 `arkcli helper` TTY 菜单;应选择 `helper configure/mcp/supabase/list/status/reset` 的最具体子命令。
27
27
 
28
28
  ## Guard / 守卫
29
29
 
@@ -46,6 +46,10 @@
46
46
 
47
47
  ```bash
48
48
  arkcli helper list --format json
49
+ arkcli helper status codex --format json
50
+ arkcli helper configure codex --profile <agent-plan-profile> --model <model-id>
51
+ arkcli helper configure codex --profile <platform-profile> --endpoint <ep-id>
52
+ arkcli helper configure pi --profile <plan-profile> --model <model-id>
49
53
  arkcli helper configure codex --profile <agent-plan-profile> --model <model-id> --with-mcp
50
54
  arkcli helper configure codex --profile <agent-plan-profile> --model <model-id> --with-mcp --keep-native-websearch
51
55
  arkcli helper configure codex --profile <agent-plan-profile> --model <model-id> --with-mcp --with-supabase
@@ -56,7 +60,6 @@ arkcli helper mcp codex --profile <agent-plan-profile> --capability datapro
56
60
  arkcli helper mcp codex --profile <agent-plan-profile> --capability web-search
57
61
  arkcli helper mcp codex --profile <agent-plan-profile> --capability agent-memory --ov-resource <database-name>
58
62
  arkcli helper mcp codex --profile <agent-plan-large-or-max-profile> --capability cua
59
- arkcli helper configure pi --profile <plan-profile> --model <model-id>
60
63
  ```
61
64
 
62
65
  `arkcli helper` 无子命令的 Harness 矩阵只允许真人在 TTY 中运行,不纳入 Agent 自动执行的 happy path。