@volcengine/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bin/arkcli-darwin-amd64

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/bin/arkcli-darwin-amd64
+size: 40629584 bytes
+sha256: a15a2e1907422627fa031ea8be46e01446bc6b72ece0f03558a6b88c62598599

package/manifest.json

@@ -0,0 +1,37 @@
+{
+  "version": "1.0.46-prerelease.46bd0d6dcc58",
+  "platforms": {
+    "darwin-amd64": {
+      "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.46-prerelease.46bd0d6dcc58/arkcli-1.0.46-prerelease.46bd0d6dcc58-darwin-amd64",
+      "sha256": "a15a2e1907422627fa031ea8be46e01446bc6b72ece0f03558a6b88c62598599"
+    },
+    "darwin-arm64": {
+      "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.46-prerelease.46bd0d6dcc58/arkcli-1.0.46-prerelease.46bd0d6dcc58-darwin-arm64",
+      "sha256": "76ac7070fff6851e290895e38e219c66105b3fa0990f7d48c5d4b246b79e98e6"
+    },
+    "linux-amd64": {
+      "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.46-prerelease.46bd0d6dcc58/arkcli-1.0.46-prerelease.46bd0d6dcc58-linux-amd64",
+      "sha256": "c7100a385086235b9d505be52ac8072305020dfedae5a161526b59e37159c0be"
+    },
+    "linux-arm64": {
+      "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.46-prerelease.46bd0d6dcc58/arkcli-1.0.46-prerelease.46bd0d6dcc58-linux-arm64",
+      "sha256": "de345d949150e09b53090078035221e13f0f290a9fd8ac95401e3a1d6d491f0f"
+    },
+    "windows-amd64": {
+      "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.46-prerelease.46bd0d6dcc58/arkcli-1.0.46-prerelease.46bd0d6dcc58-windows-amd64.exe",
+      "sha256": "d36d1ba5592bc373303c7c2bd4bfe9c130599aa98f76a7a5d268ebb11042abc2"
+    },
+    "windows-arm64": {
+      "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.46-prerelease.46bd0d6dcc58/arkcli-1.0.46-prerelease.46bd0d6dcc58-windows-arm64.exe",
+      "sha256": "60bf3e8463d0fc9088b524cc9d613fdba661b6f4c6d655a3ce7e93d16849d390"
+    }
+  },
+  "skills": {
+    "primary": {
+      "url": "https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/prerelease/1.0.46-prerelease.46bd0d6dcc58/skills.tar.gz",
+      "sha256": "587b0421f4ac6d2633e7159574e22be1517285f6afc448d70484f3b58d7a1b76",
+      "kind": "cdn"
+    },
+    "tag": "v1.0.46-prerelease.46bd0d6dcc58"
+  }
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@volcengine/ark-cli-darwin-x64",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.46-prerelease.46bd0d6dcc58",
+  "description": "ArkCLI volc binary and Skills for darwin-amd64",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "license": "Apache-2.0",
+  "files": [
+    "bin",
+    "skills",
+    "manifest.json",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/arkcli-agent/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: arkcli-agent
+version: 1.1.5
+description: "arkcli agent：管理 ARK Managed Agents，包括 Agent / Skill / Env / Session / File / Memory Store / Vault / MCP OAuth。控制面优先走 ForTop/OpenTOP，Session 运行时和 Files 走数据面直联。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli agent --help"
+---
+
+# arkcli agent
+
+**CRITICAL — 开始前 MUST 先读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)。**
+
+当用户需要创建、查询、调试或联通 ARK Managed Agent 时使用本 skill。核心原则：先用稳定产品命令，不要直接猜 OpenTOP Action；Session 运行时资源、事件、线程、Files API 走数据面直联；MCP OAuth 登录先查后端 provider，再用 `arkcli agent +mcp-login`。
+
+执行前按“先选路径”读取对应 reference；只读相关 reference，不需要一次性加载全部细节。用户请求如果已经明确是创建、复制、挂文件、聊天、MCP 登录等写操作，完成必要确认/消歧后直接执行，不要只给命令建议。
+
+## 创建 Agent 的最小决策表
+
+用户要求 Vision / Ultra / 视觉创作 Agent，或召回资料提到 `ultra_vision_agent_preview` 时，先读 [Vision Agent](references/vision-agent.md)，不要套用下方普通 Agent 主模型与默认工具流程。仅要求“会生图”不等于指定 Vision 类型。
+
+仅咨询参数含义、命令用法或解读已有完整 stdout 时，能从文档与当前证据回答就直接回答，
+不为概念解释发起 live 查询。只有账号当前配置、资源状态或模型实时可用性等问题才查服务端。
+已拿到完整结果时复用它；名称搜索/grep 无命中不等于资源不存在，先确认目标是 Agent、
+Environment 还是 Session。用户提供明确 ID 时直接查对应资源，不先列全量清单。
+
+用户明确使用第三方模型/BYOK 时，先读 [BYOK 模型配置与请求凭证](references/byok.md)。不要把该模型强行匹配到 ArkModels，也不要自动改用方舟模型。
+
+| 用户输入 | AI Agent 的处理 |
+| ---- | ---- |
+| 未指定 Agent 主模型 | 创建任务有自然语言意图时，用 `arkcli agent model list --query "<用户意图>" --format json` 完整取候选并有据择优；仅列白名单时用 `arkcli agent model list --format json`。明确硬指标再按具体版本查 metadata，不凭记忆拼 ID |
+| 需要为工具选择绑定模型 | 用 `agent model list --usage tool --format json`；不默认加 `--primary-only`，选中的 `items[].model` 填入 `Tools[].Configs[].Models[].ID`，不修改 Agent 主模型 |
+| 未指定 Skill | 先查本账号 custom skill；没有合适候选再查 market/SkillHub skill |
+| 给出本地 Skill zip | 先调用 `agent skill create --zip`，拿到返回的 `skill-...` ID 和版本后再创建 Agent |
+| 未指定工具 | 使用 CLI 注入的完整默认工具集；显式传 `--tool` 时全量替换默认工具 |
+| 未明确要求工具模型绑定 | 不查询工具模型，不自行添加 image_generate/video_generate 或其 Models；保留普通默认工具。明确要求 Todo 时按 [Todo 配置](references/todo-write.md)添加所属工具集，但不启用生图/视频 |
+| 未指定环境 | 先确认 Session 的实际 Project，再选择同 Project 的 Environment 并显式传 ID；不得从 account-wide 结果直接取最新环境，见 [项目一致性](references/session-files.md#session-项目一致性) |
+| 创建成功 | 必须回读 `agent agent get <agent-id> --format json`，展示服务端最终的 Model、System、Tools、Skills、McpServers 和扩展配置 |
+| 用户期待 Agent 回复 | 短请求使用 `+new session ... --message` 或 `events send ... --stream`；大 payload / 长耗时任务使用 `events send --poll`，或 send 立即返回后按 cursor 轮询 events / 使用 `+tail`，不要让所有任务都阻塞等待 |
+
+## 业务目标澄清
+
+模型、Agent、Skill、MCP provider 等目标无法唯一确定时，遵循
+[`arkcli-shared`](../arkcli-shared/SKILL.md) 的 0/1/N 结构化选择契约：先做一次最小
+只读查询，选项只取本轮完整结构化结果中的真实 ID 和区分字段。多个候选会改变远端结果
+时使用宿主结构化选择能力；唯一候选直接继续。选择目标只完成消歧，不等于授权后续创建、
+更新或删除。
+
+**创建任务的主模型选型例外**：默认由 AI 按本轮 `--query` 详情、实时资格与用户意图
+择优，复述真实 `items[].model` 和依据；不能只因有多个候选就停下来问，也不能把排序第一
+当作证据或把择优说成“只有一个模型可用”。用户明确的硬指标须用对应版本 metadata
+验证；不能自动换身份、计费路径、超出预算或替换用户明确给出的模型。
+只有多个候选的能力、版本或费用会实质影响结果且无法从用户意图安全判断时，才进入
+模型选择停点：展示真实候选，用户选定前不得查询 Agent Skill，也不得执行 preview、
+`agent agent create/update`、`+new-agent`、`+iterate` 或准备后续参数。此时选项是当前
+回合的最终输出，之后不再探测写命令 `--help` 或调用其他工具。择优不替代执行授权，
+也不适用于复制、更新、删除时对已有 Agent 的目标消歧。
+
+## 先选路径
+
+| 用户意图 | 首选命令 | 细节 |
+| ---- | ---- | ---- |
+| 仅开通 MA 服务（火山） | `arkcli agent activate`；不创建资源、不开通模型 | [`references/activation.md`](references/activation.md) |
+| 创建 / 更新 / 删除 Managed Agent | `arkcli agent agent ...` | [`references/agent.md`](references/agent.md) |
+| 启用 / 关闭 Todo 任务计划工具 | `agent agent create/update --tool`；非基础 toolset、不需要 Models | [`references/todo-write.md`](references/todo-write.md) |
+| 复制已有 Agent 并改名 / 局部覆盖配置 | `arkcli +new-agent --fork <agent-id> [--name <new-name>]` | [`references/agent.md`](references/agent.md#复制-agent) |
+| 为创建 Agent 选择可用模型 | `arkcli agent model list` | [`references/agent.md`](references/agent.md#模型选择) |
+| 查询 Vision / Ultra 视觉主模型（仅火山） | `arkcli agent model list --usage vision` | [`references/vision-agent.md`](references/vision-agent.md) |
+| 为生图/生视频等支持模型绑定的工具选择模型 | `arkcli agent model list --usage tool` | [`references/agent.md`](references/agent.md#查询工具模型与缓存) |
+| 查询模型运行参数的可选值和默认值 | `arkcli agent model config <foundation-model-name>` | [`references/model-config.md`](references/model-config.md) |
+| 创建 Agent 时选择 Skill | 默认先查 custom，未命中再查 market；用户明确指定 market 时跳过 custom | [`references/skills.md`](references/skills.md) |
+| 查询/使用本账号 custom skill | 先 `agent skill list --source custom --limit 100`，无匹配时沿 `NextPage` 传 `--page` 继续；需要完整候选时再用 `--page-all` / `--skill <skill-id>` | [`references/skills.md`](references/skills.md) |
+| 查询 Ark Skill / 跨来源查询 | `agent skill list --source ark` 或 `--source all`；Ark Skill 只读 | [`references/skills.md`](references/skills.md) |
+| 上传本地 custom skill zip | `arkcli agent skill create --zip <file>` 或 `agent agent create --skill-zip <file>` | [`references/skills.md`](references/skills.md) |
+| 扫描或导入 GitHub Skill | `agent skill github scan <repo>` / `agent skill github import <repo> --path ...|--all` | [`references/skills.md`](references/skills.md#from-github-import) |
+| 管理 custom Skill 版本 / 删除 Skill | 先完整列出版本，再按“非 latest → latest → Skill”的依赖顺序删除 | [`references/skills.md`](references/skills.md) |
+| 创建运行环境 / 会话 | `arkcli agent env ...` / `arkcli agent session ...` | [`references/session-files.md`](references/session-files.md) |
+| 自托管环境 / Work Queue 排障与停止任务 | `agent env create --runtime-type self_hosted` / `agent env work list/get/stats/stop` | [`references/self-hosted.md`](references/self-hosted.md) |
+| Environment 初始化脚本 | `arkcli agent env create/update --setup-script @./bootstrap.sh` | [`references/session-files.md`](references/session-files.md#environment-自定义脚本) |
+| Session 一次性覆盖 Agent / Environment | `arkcli agent session create --agent-overrides ... --environment-overrides ...` | [`references/session-files.md`](references/session-files.md#session-overrides) |
+| 升级已有 Session 的模型 / Agent 版本 / 运行配置 | `arkcli agent session upgrade <session-id>` | [`references/session-upgrade.md`](references/session-upgrade.md) |
+| Session 创建时绑定 TOS 目录 | 用户明确提供地址后使用 `arkcli agent session create --tos-path tos://<bucket>/<prefix>/`；未提供时先询问，不猜路径 | [`references/session-files.md`](references/session-files.md#session-tos-资源) |
+| 选择/继续 Managed Agent 会话 | `arkcli +new session` | [`references/events-chat.md`](references/events-chat.md) |
+| 直接创建新会话并聊天 | `arkcli +new session <agent-id> --environment-id <env-id>` | [`references/events-chat.md`](references/events-chat.md) |
+| 给已有会话发消息或实时看回复 | 默认 `events send` 只负责写入；需要 SSE 回复时加 `--stream` 自动跟随 event cursor（`--wait` 保留为兼容别名），实时入口默认请求 `agent.message` / `agent.thinking` Event Deltas；也可使用 `+tail`/`events stream`，`--no-event-deltas` 回退完整事件；`+new session`/`+iterate` 内部自动使用补偿 channel | [`references/events-chat.md`](references/events-chat.md) |
+| 主动压缩会话上下文 | `arkcli agent session compact <session-id> [--instructions <text|@file>]` | [`references/events-chat.md`](references/events-chat.md) |
+| 配置自动上下文压缩（compaction） | Agent create/update `--context-management`；新 Session 的 `--agent-overrides` | [`references/context-management.md`](references/context-management.md) |
+| 看 session 诊断 / 导出诊断包 | `arkcli +debug <session-id>` / `arkcli +export <session-id>` | [`references/debug-export.md`](references/debug-export.md) |
+| 上传文件并挂到已有 session | `arkcli agent session resources add <session-id> --path <file>` | [`references/session-files.md`](references/session-files.md) |
+| 只上传 / 查询 Files API 文件 | `arkcli agent file upload/list/get/wait/delete` | [`references/session-files.md`](references/session-files.md) |
+| 管理 memory store / memories | `arkcli agent memory-store ...` | [`references/interfaces-gaps.md`](references/interfaces-gaps.md) |
+| 整理会话记忆、创建或观察 Dream 任务（仅火山） | `arkcli agent dream create/list/get/cancel/wait` | [`references/dream.md`](references/dream.md) |
+| 查询可挂载 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) |
+
+## 模型查询：主模型与工具模型
+
+- Vision / Ultra 主模型使用 `--usage vision`，与前端独立配置对齐，不能用普通 Agent 或工具目录替代。默认选择、环境和筛选边界见 [Vision 模型查询](references/vision-agent.md)。
+- 默认 `--usage agent` 按 `ep_agent.support` 选择主模型；`--usage tool` 按具体版本的 `epa_tool_model.support` 选择工具模型，两者不取交集。两种查询都不默认加 `--primary-only`，也不默认按 `primary_version` 排除候选；只有用户明确要求“只看主版本”时才加。
+- 工具候选使用返回的 `items[].model`，不是内部 `id`（如 epm-*）。只给支持绑定的工具配置 `Models`；字段含义与完整 Tools 替换示例见 [工具模型绑定](references/agent.md#工具绑定模型仅部分工具支持)。
+- 两种用途共享 5 分钟全版本 ArkModels 缓存，输出 `cache.source/fetched_at/expires_at`；只有需要刷新时才加 `--refresh-cache`，不要每次查询都强刷。失败冷却为 1 分钟，强刷也不能绕过；错误不等于空候选。
+- 列表不截断数量；上下文/模态/能力筛选不再由 list flags 承担。只有用户明确提出这些要求时，才按候选的 `name` + `version` 查询 `ListModelMetaDatas` 后筛选；无额外要求不逐模型补查。流程、字段与缺失值处理见 [按具体版本筛选](references/agent.md#按具体版本筛选)。
+- `agent model config` 查询运行参数，不提供工具支持性。用户明确给出的模型 ID 仍交给创建/更新接口判断，不把缓存查询变成写入硬拦截。完整参数、缓存隔离与 query 模式边界见 [查询说明](references/agent.md#查询工具模型与缓存)。
+
+## 认证与 Profile
+
+- 未显式提供 API Key 时，Managed Agent 使用 `type=platform` 的 Profile，不自动使用 Agent Plan / Coding Plan（含团队版）的套餐凭证。登录成功不代表默认 Profile 支持 MA。
+- 需要使用 Profile 凭证时，用 `auth status --format json` 核对类型；默认是套餐类型时，对本次命令指定已确认的 `--profile <platform-profile>`，不自动执行 `profile use` 改全局默认。没有可用 Platform 或身份/项目不明确时，按 Profile Skill 处理并取得确认，不猜名称或跨账号重试。
+- 数据面命令接受显式 `--api-key` 或 `ARK_API_KEY`，此时即使默认是套餐 Profile，也不会因其类型被拦截。优先级为 `--api-key` > `ARK_API_KEY` > Platform Profile 的 Key；Key 的有效性与权限由服务端验证，认证失败时停止，不跨账号重试。
+- 未显式指定地址时，MA 根据当前产品、Region、`--env` 使用标准数据面地址，不继承 Profile 的套餐或自定义路由。仅提供 Key 即可调用数据面，无 Profile 也不必额外提供地址。显式 `--base-url` / `ARK_BASE_URL` 优先，但必须同时显式提供 Key；只覆盖地址不能替换套餐凭证。
+- 控制面仍依赖登录凭证，纯控制面命令不接受 Key/地址覆盖；包含控制面步骤的混合流程也不能只靠 API Key 免登录。涉及控制面时先 `arkcli auth status --format json`，处理未登录、SSO 过期或 STS refresh 失败。仅使用显式 Key 的数据面调用不要求先登录。
+- 真实执行返回 `managed_agent_profile_required` 时停止，不改走 raw API 绕过。离线 `--dry-run` 不检查在线资格，预览成功不代表真实调用成功。上述覆盖均只影响本次调用，不修改默认 Profile 或保存的 Key。
+- 线上环境已就位，默认走 `--env prod`，不要再默认跑 stg。
+- 用户明确要求 stg 时使用 `--env stg` 和配套 Key；未指定地址时 MA 数据面自动使用标准 stg 地址。若显式提供地址，确认它也属于目标环境（显式地址不会被 `--env` 改写）。
+- 非交互 SSO 登录是两段式：先 `arkcli auth login --no-browser` 拿 URL；用户贴回 base64 code 后，再跑 `arkcli auth login --no-browser --code <code>`。
+
+## List 分页
+
+- 支持分页契约的列表可加全局 `--page-all`；未显式传单页大小时，CLI 默认每页取 100 条。默认最多请求 10 页，可用 `--page-limit <N>` 调高，`--page-delay <ms>` 控制页间隔。
+- 已支持：Agent/版本、Env、Session、Skill market/custom/ark/all、Memory Store/Memories、Vault/Credentials/OAuth Provider、Files、Session Events/Threads。CLI 会分别按后端契约使用 `Page`、`PageNumber`、`PageToken`、`after`，并合并结果。
+- `agent model list`、`memory-store creators`、`session resources list` 没有可用分页契约，不要为它们假设 `--page-all` 能补全结果。命中 `--page-limit` 后应检查返回的 `NextPage`、`has_more` 或 `TotalCount`，判断是否仍有未拉取数据。
+
+## 删除确认
+
+- Managed Agent 的破坏性 `delete` 命令在真实 TTY 且未传 `--yes` 时会显示不可逆警告并询问 `[y/N]`；输入 `y/yes` 才会调用后端，其他输入会取消。
+- 非交互环境（AI Agent、CI、管道）不会读取 stdin；未传 `--yes` 时返回 `type=requires_confirmation`，不会调用后端。只有用户已经明确确认删除目标后，调用方才可以补 `--yes` 重试。
+- `--dry-run` 不是全域能力。只有命令自身 `--help` 列出该 flag 时才可用；
+  当前主要覆盖可由本地 payload 确定的 Env/Session/Memory/Vault/Credential
+  写请求，以及 `agent agent create/update/delete`、`agent skill create/update/delete`
+  和 `agent file upload/delete`，以及会写本地文件的 `agent skill download`、
+  `+export`。`+new-agent`、`+iterate`、MCP login 与所有纯读命令都不注册。
+  Client Preview 只生成零网络 `preview.v1` 计划；它不代替真实执行前的开通、
+  版本/依赖校验或删除确认。
+
+## 长流程执行规则
+
+- 一个 shell/tool 调用只执行一个 `arkcli` 命令。不要把 `session create`、写入 ID、`events send`、`events list` 用 `&&`、`;`、管道或 heredoc 串成一个长命令。
+- `session create`、Agent 创建、文件上传等写操作成功后，立即从结构化输出提取并保存 ID；下一次调用使用已经确认的字面量 ID，不要依赖同一 shell 中的变量赋值继续执行。
+- 任一步超过预期时间时，先结束该步并单独执行 `session get`、`events list` 或 `+debug` 诊断；不要让后续命令被前一个阻塞步骤掩盖。
+- 大 JSON 或大文本不要在同一个 shell 调用中通过 Python/Node 管道解析；先让 `arkcli --format json` 独立返回，再在下一步解析结果。这样即使请求超时，也能区分是创建、发送还是回查阶段失败。
+
+### 超时与重试
+
+- Dream 创建不自动重试。超时、连接中断或响应解析失败都可能已创建任务；先用返回 ID 查询，未拿到 ID 时检查 `agent dream list`，不要直接重新创建。`dream wait` 超时或中断只停止本地等待，不取消远端任务。
+
+- 只对网络超时、连接中断、429 或 5xx 做有限重试；参数校验、鉴权失败、未开通、权限不足和明确业务错误直接抛出，不要重试。
+- `session create` 超时后结果可能未知。先用 `session list/get` 按返回的标题、Agent、环境和创建时间检查是否已经创建，再决定是否重试；没有幂等键时不要盲目重复创建。
+- `events send` 超时后也可能已经被服务端接收。先用返回的 event cursor、发送时间或最近的 user event 查询 `events list`；确认没有接收记录后才允许重试，避免重复发送用户消息。
+- `events send --stream` 达到 stream 等待上限后自动转为 events list polling，默认再等待 120 秒。两阶段都超时后只读恢复，不重发；再次执行 `events send --poll` 会发送新消息，不是续等。
+- 原始 `events list --after` 可能返回历史，不能用旧 idle 判本轮完成。异步或超时恢复必须按[事件只读恢复流程](references/events-chat.md#异步发送后的只读恢复)分页定位发送 ID、去重并核对本轮 Session 终态；没有精确边界就报告未确认。
+- 每一步都要保留步骤名、Session ID、event cursor、尝试次数和最后错误；达到重试上限后抛出带上下文的错误，不要把超时伪装成成功。
+
+## 命令速查
+
+| 命令 | 说明 |
+| ---- | ---- |
+| `arkcli agent agent list/get/create/update/delete/versions` | Agent CRUD + 版本 |
+| `arkcli agent model list` | 默认查询主模型，`items[].model` 用于 `--model`；`--usage tool` 查询工具模型，结果用于 `Configs[].Models[].ID`；`--query` 可增强详情/排序 |
+| `arkcli +new-agent` | Agent create 增强入口；支持 `--fork/--from` 复制已有 Agent 后创建新 Agent |
+| `arkcli +iterate` | 更新 Agent 配置，创建新 Session，并进入 one-shot/REPL 试运行；创建前核对项目一致性，显式传入同 Project 的 `--environment-id/--env-id` |
+| `arkcli agent skill search/list/get/create/update/delete/versions/download/set-protection/github` | Market/custom/Ark Skill 查询、GitHub 导入、custom Skill 保护与版本管理；Ark Skill 只读 |
+| `arkcli agent env list/get/create/update/delete` | Environment CRUD；当前 `env list` 没有 `--status`，状态筛选规则见 `session-files.md` |
+| `arkcli agent session list/get/create/update/delete` | Session CRUD |
+| `arkcli agent session upgrade <session-id>` | 升级已有 Session 运行配置，返回受理状态；使用 snake_case 请求并回读验证 |
+| `arkcli agent session resources list/add/get` | 数据面 session resources；get 是 CLI 基于 list 的本地筛选 |
+| `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 会前置校验 |
+| `arkcli agent session compact <session-id>` | 主动压缩上下文；正常 thread idle/end_turn + session idle/end_turn 表示命令完成，compacted 事件是可选的实际压缩确认 |
+| `arkcli agent session threads list/get` | 数据面 threads |
+| `arkcli agent file list/get/upload/wait/delete` | 数据面 Files API |
+| `arkcli agent memory-store list/get/create/update/delete` | Memory Store CRUD |
+| `arkcli agent memory-store memories list/get/create/batch-create/update/delete` | Memory CRUD |
+| `arkcli agent vault list/get/create/update/delete` | Vault CRUD |
+| `arkcli agent vault oauth-provider list` | 查询后端已注册 MCP Provider；返回的 MCP server 信息可用于 Agent `--mcp-server` |
+| `arkcli agent vault oauth-flow create` | 裸创建 Vault OAuth Flow，适合脚本自带 redirect URL |
+| `arkcli agent vault credentials list/get/create/update/delete` | Credential CRUD |
+| `arkcli agent +mcp-login` | 托管 MCP OAuth 登录：本地 callback + CreateVaultOAuthFlow + 等待 credential 创建 |
+| `arkcli +chat <prompt>` | Responses API 快速对话；不要把它当 Managed Agent session 入口 |
+| `arkcli +tail <session-id>` | 人类可读 event stream |
+| `arkcli +new session` | Managed Agent session 选择器；可继续已有 session，或选 agent/env 起新 session |
+| `arkcli +new session <agent-id> --environment-id <env-id>` | Managed Agent 新 session 直达入口；固定先创建新 session，再 REPL / one-shot |
+| `arkcli +debug <session-id>` | 聚合 session、events、resources、threads 做诊断 |
+| `arkcli +export <session-id>` | 导出诊断 tar.gz |
+
+复杂字段如 `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`。
+
+Memory get 的 `--view` 语义：默认按 `basic` 请求，只返回 metadata 和 `ContentSha256`；`--view full` 保留 Content。若服务端仍在 basic 下返回 Content，CLI 会在输出层剥离 Content，但这只能控制输出，不能挽回已经产生的网络传输；服务端仍需正确实现 View 参数以节省带宽。
+
+## 参考
+
+- [`references/agent.md`](references/agent.md)：创建、复制、查找 Agent、默认工具、工具模型绑定与查询缓存。
+- [`references/skills.md`](references/skills.md)：Market skill 搜索、custom skill zip 上传、skill ref 组装。
+- [`references/session-files.md`](references/session-files.md)：Env / Session / Files API / Session resources。
+- [`references/events-chat.md`](references/events-chat.md)：events send/list/stream、`+new session` 选择器、`+tail`。
+- [`references/mcp-vault.md`](references/mcp-vault.md)：Vault、Credential、MCP OAuth、Agent 挂 MCP。
+- [`references/debug-export.md`](references/debug-export.md)：`+debug`、`+export`、端到端验证模板。
+- [`references/interfaces-gaps.md`](references/interfaces-gaps.md)：接口链路和当前 gap。
+- [`references/evals.md`](references/evals.md)：Agent/Skill/GitHub/Compact 最小评估用例。

package/skills/arkcli-agent/references/activation.md

@@ -0,0 +1,23 @@
+# 开通 Managed Agent 服务（仅火山）
+
+用户只要求开通 MA 时使用 `arkcli agent activate`，不要创建测试 Agent、Session 或发送消息来代替开通。此入口仅适用于火山版。
+
+先按共享规则执行 `auth status --format json`，确认当前账号、认证状态和 Platform 上下文。该命令使用控制面登录凭证，API Key 不能代替登录。开通属于账号级计费能力操作；需告知用户并取得明确确认。
+
+```bash
+arkcli agent activate
+```
+
+- 已开通：返回 `activated=true, already_activated=true`，不重复开通。
+- 未开通：真实终端询问确认；`--yes` 只跳过真实终端的确认。非交互环境单独加 `--yes` 不授权开通。
+- 已取得用户明确开通授权时，非交互调用可使用下面的命令（AI 调用仍需附加共享 Skill 的归因前缀）：
+
+```bash
+ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 arkcli agent activate --yes
+```
+
+成功后 `activated=true, already_activated=false`。只开通 `DataManagedAgentSum` 的 `sandbox`、`web_search`，并轮询确认状态；不激活模型、不创建 Agent/Environment/Session、不购买套餐、不修改 Profile。
+
+查询失败或状态未知时停止，不以 Agent 列表可访问作为已开通证据。开通失败时保留服务端错误；开通后状态确认超时不代表服务端没有生效，先核对状态，避免盲目重试。
+
+该命令依赖在线状态决定跳过或开通，不提供 `--dry-run`。`agent agent create` / `+new-agent` 仍保留原有的自动开通流程，模型开通是另一项独立操作。