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

package/skills/arkcli-gen/references/image-stream.md

@@ -0,0 +1,105 @@
+---
+name: image-stream
+description: arkcli +gen --stream 图片流式输出。每行一个 image_generation.* 事件 JSON (NDJSON), 适合做增量预览 / 可视化进度 / 结合 jq 提取每帧 URL。
+---
+
+# +gen --stream（图片流式）
+
+`+gen` 默认是同步等待整个生成完成；`--stream` 让 CLI 切换到 NDJSON 输出，把服务端 SSE 流式事件原样吐到 stdout，每行一个事件。适合：
+
+- 多图生成场景 (`--image-count >1`)，想要看到第一张就立刻处理
+- 接 jq / 脚本流水线，做增量预览或并行下载
+- 调试服务端流式行为
+
+## 适用范围
+
+**仅图片任务**。视频任务走的是异步 task + polling 模型（`+gen` 自身轮询），没有 SSE 通道；传 `--stream` + 视频模型会被 `+gen` 前置拦截：
+
+```
+--stream only applies to image generation tasks
+hint: remove --stream (video tasks use async polling, not SSE),
+      or pass --modality image with an image-capable model / endpoint
+```
+
+## 事件协议
+
+底层走 SDK `arkruntime.Client.GenerateImagesStreaming`，三类事件：
+
+| 事件类型 | 何时发 | 携带字段 |
+|---|---|---|
+| `image_generation.partial_succeeded` | 每张图片生成完成 | `url` / `b64_json` / `size` / `image_index` / `model` / `created` |
+| `image_generation.partial_failed` | 单张图片生成失败（不一定终止流式） | `error.code` / `error.message` |
+| `image_generation.completed` | 流式终结 | 可选 `usage{generated_images, output_tokens, total_tokens}` / `tools[]` |
+
+CLI 输出每行一个 `ImageStreamDelta` JSON（service-layer 视图），关键字段：
+
+```json
+{
+  "event_type": "image_generation.partial_succeeded",
+  "model": "doubao-seedream-5-0-260128",
+  "created": 1700000000,
+  "image_index": 0,
+  "url": "https://...",
+  "size": "1024x1024"
+}
+```
+
+注意：
+- `partial_failed` 的 `error.code/message` 在 ImageStreamDelta 里是 `error_code` / `error_message` 两个 flat 字段
+- `completed` 事件的 `usage` / `tools` 在 ImageStreamDelta 里改名为 `final_usage` / `final_tools`
+- `b64_json`（base64 编码图片）字段只有当 ResponseFormat 为 `b64_json` 时才出现（默认 `url`）
+
+## 命令速查
+
+```bash
+# 1. 流式生成单张图（看第一帧就能下手处理）
+arkcli +gen "neon kitten" --model doubao-seedream-5-0-260128 --stream
+
+# 2. 流式生成 3 张图，按顺序拿 URL
+arkcli +gen "5 different futuristic cars" \
+  --model doubao-seedream-5-0-260128 \
+  --image-count 3 --stream \
+  | jq -r 'select(.event_type=="image_generation.partial_succeeded") | .url'
+
+# 3. 流式 + 解 base64（要先把 b64_json 切到 stream 上）
+arkcli +gen "blue laptop" \
+  --model doubao-seedream-5-0-260128 --stream \
+  | jq -r 'select(.b64_json != "") | .b64_json' \
+  | base64 -d > out.png
+
+# 4. 监控错误事件 + 终结 usage
+arkcli +gen "..." --model ... --stream \
+  | jq 'select(.event_type=="image_generation.partial_failed" or .event_type=="image_generation.completed")'
+```
+
+## 与 `--save-to` 的关系
+
+`--save-to` 是同步路径上的"自动下载"功能；`--stream` **不会触发自动下载**。
+
+理由：流式的目的是让用户增量处理输出，CLI 不应该并行落盘干扰。需要同时落盘 + 流式监控时，自己 pipe 流式输出到下载脚本即可（见上面例 3）。
+
+## 与 raw API 的关系
+
+`+gen --stream` 等价于：
+
+```bash
+arkcli api arkruntime.generate_images_stream \
+  --params '{"model":"...","prompt":"...","stream":true,"response_format":"url"}'
+```
+
+但 raw API 接受不到 `arkcli +gen` 那一层的 ParseAssetRefs / collapseImageAssets / modality 路由能力。普通使用走 `+gen --stream` 即可，raw API 只在调试 SDK 字段或测试服务端行为时使用。
+
+## 不支持流式的场景
+
+| 场景 | 为什么 | 替代方案 |
+|---|---|---|
+| 解析为 video 的模型/Endpoint（或显式 `--modality video`） | 视频走异步 task + poll 模型，无 SSE 通道 | 不传 `--stream`；用 `+gen` 默认轮询 |
+| 同步等待累计结果 | `--stream` 模式下 stdout 是 NDJSON 流，不输出累计 GenerateOutput | 不传 `--stream`；走默认同步路径 |
+
+## 常见错误
+
+| 现象 | 原因 |
+|---|---|
+| `--stream only applies to image generation tasks` | 结构化元数据把模型/Endpoint 解析为 video，或 `--modality video` 显式指定 |
+| 流式输出第一行就是 `partial_failed` 后再无输出 | 上游真正失败了；看 `error_code` 字段；尤其常见于 `--size 1024x1024` 这种小尺寸 |
+| 看不到 `completed` 事件 | `--image-count 1` 时服务端可能不发 completed，单张就是终结；多张才会发 |

package/skills/arkcli-gen/references/intent-and-validation.md

@@ -0,0 +1,177 @@
+# 从用户要求到可验收成品
+
+宿主的额外约束优先：要求强制水印时不得关闭；凭证由宿主注入且禁止本地恢复时，
+认证错误只能停止并报告，不能启动登录、刷新或切换凭证。本参考不放宽共享 Skill 的这些边界。
+
+## 1. 意图、默认值与准入
+
+先区分：真实生成、编辑已有素材、查询已有任务、只预览请求。真实生成不是只读；
+`--dry-run` 不能证明 Key 有效或成品达标。用户只要预览时保持全程本地，不先做在线准入查询。
+
+把明确要求保留成检查清单：主体/数量、属性/文字、相对位置、尺寸/比例、时长、动作及方向、
+必须保留/必须排除、输入素材角色、文件数量与交付位置。不要把用户硬要求当作可随意优化的文案。
+不需要把整张清单都复述给用户，只在有冲突或会改变结果时说明。
+
+素材集合也是硬约束：不得引入用户未提供或未明确授权复用的历史图片、视频、音频；目录里“看起来相关”
+的旧文件不能自动成为参考素材。用户只给一个视频时，不因为 Skill 示例里有角色图就擅自补一张图。
+
+- 用户未选模型：优先当前目标模态的兼容 default；无 default 时按共享 0/1/N 规则处理真实候选。
+- 未说图片数量：一张；“四格漫画”不等于四个文件。未指定的尺寸、时长等沿用选定模型的有效默认，
+  不套用其他模型的参数。默认影响用户目标（例如横竖构图）时在结果中说明。
+- 用户要图片/视频：显式带对应 `--modality`。模态不明确才澄清，不从品牌名猜测。
+- 同一次 workflow 的查询、提交、轮询保持相同 Profile/凭证/region。临时参数不写回 default。
+- 按共享 execution-context 的五类 Profile 矩阵读取 `invocable` 与 `required_overrides`。
+  本地显示已登录、Key 缓存状态、资源可见都不能单独证明数据面 Key 当前有效。
+  实际任务响应才证明本次调用被接受；不为每次生成额外提交一张“试钥匙”的图片。
+
+## 2. 参数组合不是关键词到 flag 的固定替换
+
+`supported_params` 描述 wire 参数（下划线）；CLI flag 通常是连字符，且存在映射：
+
+| 用户约束 | CLI / wire 约束 |
+| --- | --- |
+| 多张图片 | `--image-count N` / `--n N`；N>1 导出 sequential auto 与 max_images。不要同时传两个数量入口 |
+| 连续图模式 | `--sequential auto|disabled` → `sequential_image_generation`；裸 flag 缺值，disabled 会与多图要求冲突 |
+| 无水印/无声音 | 支持该值时显式 `--watermark=false` / `--generate-audio=false`；false 与省略不同 |
+| 固定画面 | prompt 保留视觉要求；`camera_fixed` 支持时才额外加 flag，验收也要检查镜头变化 |
+| 视频时长/帧数 | 先查 duration/frames 能力与覆盖关系，不同时堆参数后假设两者都生效 |
+| 一张多格图 | 一张图片 + prompt 指定格子布局；不是默认 sequential 多文件 |
+| 输入参考/首尾帧 | 先确定单图首帧 / 首尾帧 / 多参考模式，再为每张图显式标 `first_frame` / `last_frame` / `reference_image`；不把参考图误作首帧，也不把首帧与多参考混在一次请求 |
+| 视频续写 | `reference_video` 明确源视频，人物图只作 `reference_image`；ratio 逐值服从精确模型/EP 能力，不固定替换成 `adaptive` |
+| 只要 URL | 显式 `--save-to=""`；不能用省略代替空串，不能声称已保存本地 |
+
+对实际会发出的每个模型参数，检查 support、type、enum、min/max、required、fixed/default、description 及组合依赖。
+**`description` 不是注释，是条件约束的唯一载体。** 实测 74 个参数条目中 `description` 填充率 100%，而 `min/max` 仅 9%、`enum` 仅 19% —— 结构化字段看着「有」的多数是空的。四类只在 `description` 里的信息：
+值域补充（`duration` 的「4-30 **或 -1**」）、条件子集（`ratio` 的「编辑任务**仅允许** adaptive」）、跨参数依赖（`omni_reference_task_type` 四种取值各自的 `ratio`/`duration` 约束）、替代方案（`frames` 的「请使用 duration」）。
+**`default` 是目录自己声明的合法值，与 `min/max` 冲突时以 `default` 为准** —— `duration` 的 `default=-1` 就落在它自己的 `min=4 / max=30` 之外，只看 `min/max` 会判 `-1` 非法，而 `-1` 恰恰是 auto 模式下唯一安全的取值。
+`--wait`、`--save-to`、`--open` 等客户端编排 flag 不属于模型参数目录。
+明确不支持的键/值不能靠 `--extra-body`、`--force` 或改拼写偷偷绕过。
+取值等于目录 `default` 却被 CLI 拒绝时，**这是 CLI 与上游目录的冲突，不是用户的参数错**：保留冲突证据（模型名 / 参数名 / 目录 `min`·`max`·`default` / CLI 报错）并报告，不要用 `--force` 把它伪装成「参数已提交」。
+
+seedance 类视频模型还会按 **prompt 语义**自行判定任务类型（`multimodal_to_video` / `video_editing` /
+`video_extension`），不只看参数。prompt 读起来像“参考这个视频的画面/镜头顺序”时会被判成
+`video_editing`，此时 `ratio` 必须为 `adaptive`、`duration` 必须为 `-1`，且输入视频本身须落在 4~30 秒；
+否则**提交会成功拿到 `task_id`，但任务在执行阶段失败**（`InvalidParameter.TaskTypeConstraint`）。
+所以“提交返回 200”不是参数合法的证据，必须轮询到终态才能判定。
+
+目录为空/查询失败是“能力未知”，不是“全部支持”或“模型不支持”。保留告警，勿宣传
+CLI 的保守兜底值是模型推荐值。目录支持而本地拒绝时记录调用 ID、查询 Name/Version、
+拒绝参数与错误，不替换套餐调用身份。用户未授权放宽硬要求时不能静默删参数。
+
+尺寸/时长不合法时，从该版本的真实 enum/min/max 找到就近合法档位并解释差异；不能照搬别的模型的
+固定“至少 5 秒/某分辨率”。改变时长、画幅、数量或费用前让用户确认，不把不合法值原样提交反复试错。
+若要求必须精确满足而当前模型不支持，明确冲突，不以自动放大后的成品宣称满足原要求。
+
+首次真实生成前一次核对已知的身份/lane、模型权限、模态、参数和所需素材缺口；已有本轮证据直接复用，
+不要逐个报错才逐个换身份。免费额度或套餐快照不是现金余额/代金券，不能用它推断账户“足够扣款”。
+`--dry-run` 不访问余额或在线资格，不能以预览成功承诺能生成；收到资格/余额错误时报告原始条件，
+不凭历史经验要求统一充值固定金额。HTTP 200、请求受理、任务成功、下载成功是不同证据层。
+
+“只看请求”用 dry-run；“真实草稿”只有模型支持 draft 才能使用。
+不支持 draft 时如用户接受，可另选已确认兼容的低成本配置，但必须说明不是原生草稿模式。
+
+## 2.1 CLI 参数与 HTTP / SDK 请求不是同一层
+
+用户要修 HTTP/SDK 代码时，先看其实际请求，而不是把一条 `+gen` 命令改写成 JSON：CLI flag、模型参数目录、HTTP payload 各有自己的字段名、层级和默认处理。
+
+- `--input` 是 CLI 输入语法，`@本地文件`、`first:` / `ref:` 等需要 CLI 转换；不能把这些字符串原样塞进 HTTP 请求当服务端可读素材。
+- CLI 的 `first:` / `last:` / `ref:` 会补成 wire role，但 Agent 生成命令时应优先写 SDK 完整名
+  `first_frame:` / `last_frame:` / `reference_image:` / `reference_video:` / `reference_audio:`，避免把本地简写
+  误当成服务端字段。Seedance 2.0 实测首帧/首尾帧模式与多参考模式互斥；需要混用时必须有该模型/Endpoint 的
+  明确能力依据，不能靠提交付费任务反复试。
+- `--wait`、`--save-to`、`--open` / `--no-open` 是客户端轮询/下载/打开行为，不是 HTTP 模型参数。图片的 image union 与视频的 `content[]` 结构也不能互抄。
+- 逐项核对真实 API 路径、精确模型/Endpoint、脱敏鉴权上下文、request body、素材可访问性及 response/error/request_id。字段映射以目标 API/SDK 契约为准，不凭 CLI flag 的连字符机械改下划线。
+- `+gen` 成功只能证明那次 CLI 工作流成功；CLI 可能补了默认值、转了素材、选了调用上下文，**不能据此声称用户原 HTTP/SDK 代码已经正确**。应指出两份请求的实际差异；未检查用户请求就明确尚未定位，不额外生成一个收费任务代替代码诊断。
+- Client Preview 只能辅助核对已知请求字段与客户端步骤，`partial/unresolved` 仍是未知，不能把预览当服务端接受证明。真实验证需用户授权，保持同模型/API/身份；不改水印策略、切 Key 或删用户硬要求。
+
+## 3. 视频续写的意图、条件依赖与批量提交
+
+以下表达进入续写分支：“续写”“接着生成”“从结尾继续”“延长这个视频”“生成第二段”以及
+`continue` / `extend`。如果用户只是要求参考原视频的风格、节奏、动作或运镜重新创作，则保持普通 R2V；
+不要把两类任务混为一谈。
+
+续写分支的硬约束：
+
+- 源视频必须显式使用 `reference_video:`；辅助人物/服装图必须使用 `reference_image:`，不能因其排在视频后面
+  就把它当首帧。`ref:` 可以表达普通 R2V（CLI 按素材类型补成 `reference_video`）；**不带任何前缀的裸视频
+  不行**——空 role 会被数据面 400 拒绝（`reference media mode requires video role to be reference_video`），
+  必须显式给 role。不要把 `ref:` 宣称为已明确进入续写语义。
+- 本地 `reference_video` 由 CLI 自动上传到 TOS，再以预签名 https URL 提交；用户不需要自备公网地址。
+  `reference_video:@/local/source.mp4` 与 `reference_video:https://...` 都可直接提交。
+  上传要求当前账号已开通 TOS：未开通时命令会在上传前失败并给出 `tos_not_activated` 与开通入口，
+  此时如实报告并停止，不要改模型、改 role 或反复重试。
+  `--inline-local` 是逃生舱，把本地文件退回 base64 内联，但**只对图片有效**：数据面**直接拒绝**视频/音频的
+  data URL（HTTP 400，`reference_video must be provided as a web url`，任务不会创建），所以续写分支不要使用。
+- 复用历史素材仍有限制：只有先前任务明确返回、且能证明对应同一源视频的有效 `output_url` 才可复用；
+  不得按文件名、画面相似或历史目录猜一个 URL。用户只有本地 MP4 时直接提交本地路径即可，不要因为
+  “没有公网 URL”而停止。
+- `adaptive` 不是续写的无条件规则。`ratio` 应按用户要求及精确模型/Endpoint 的 `supported_params` 检查
+  `support/type/enum/fixed/default`：用户要求固定比例且该值受支持时保留；用户要求继承源画幅且
+  `adaptive` 受支持时才选它；用户没要求时优先省略，交给该资源的有效默认。目录不清楚时不要强制替换。
+- `resolution`、`ratio`、`duration` 是独立参数。优先选择能够原生完成用户时长的资源；只有单任务上限不足时
+  才提出分段续写，提交前说明它会增加任务数、计费与拼接/连续性风险，不能静默把 30 秒改成 15+15。
+- prompt 从参考视频结尾后的下一瞬开始，描述**新发生的动作**并明确不重演；将人物身份、服装、场景、光线、
+  镜头轴线/景别和运动方向列为连续性约束。不要在成品未验前承诺“无缝”“零跳变”。
+
+多候选或多阶段请求先做完整批次预检：列出候选数 × 阶段数及依赖，再按当前 lane 查询套餐/免费额度。
+火山视觉免费额度命令的正确形态是
+`arkcli usage balance --type free-quota --modality ComputerVision --page-all --format json`；套餐快照使用
+`arkcli usage plan --format json`。额度快照不是预占，无法换算每个任务时不能声称“足够完成整批”；
+已明确耗尽时不先提交半批，再到中途才切路。
+
+创建与恢复规则：
+
+- 多候选默认串行创建、并行等待。每个 `+gen` 只执行一次；解析到 `task_id` 后立即持久记录，再创建下一项。
+- `--name` 不是服务端幂等键，当前 `gen list` 也不提供可靠的 name/prompt/content 证据供重建映射；不能用
+  candidate 名称或“相同 model + 最近任务”证明某个命令已经/尚未创建。
+- 创建命令超时、输出截断或进程中断且没有 `task_id` 时，把该项记为 `UNKNOWN` 并停止后续创建。
+  `gen list` 可辅助人工排查，但不能仅凭 model/status 唯一认领任务；不得自动重提，避免重复计费。
+- 只对已经记录的 task ID 使用 `gen get`。一个候选失败不复制提交，轮询失败也不回到 `+gen`。
+
+续写语义验收必须覆盖“源视频末尾约 1 秒 → 新视频开头约 1 秒”：检查开头是否重放旧情节，以及人物、服装、
+场景、光线、镜头轴线、景别、动作姿态和运动方向是否连续。任务 `succeeded` 但出现明显重演或跳变时，
+应报告“生成成功、续写效果不合格”，不能把服务端成功等同于续写达标。
+
+## 4. 错误恢复不改变收费主体
+
+- `coding-plan-team` 的 image/video 会进入 platform 后付费 lane；在提交前必须让用户
+  明确选择兼容的 `--profile` 或提供 `--api-key`。只有本地存在唯一 sibling paygo
+  profile 不构成授权，不得先发请求再提示。
+- 401/InvalidApiKey：保留准确错误，按 Auth/Profile Skill 核对当前 lane 的 Key；
+  刷新 Key 清单不等于轮转 Key。不要自动轮转、创建 Key、换账号或循环重试。
+- 403/FeatureDenied/Responses access：可能是模型资格/Endpoint 权限，不直接断言 Key 过期。
+- 429：区分限流与额度不足，不能把所有 429 当成没钱。已明确 quota exhausted 时提醒用户
+  当前资源/套餐受限，提供同一身份下已确认兼容的候选；跨收费路径或持久切换需用户授权。
+- 异步任务已被接受后，保存 task_id，仅查该任务；失败/超时不自动再提交一个收费任务。
+- 所有错误只报告已取得的证据，不虚构剩余额度、轮转必要性或已完成状态。
+
+## 5. 完成状态、交付与语义分别验收
+
+先确认**驱动当前 Agent 的宿主模型**能否接收图片/视频，不要用生成模型的能力代替
+宿主能力。存在 `Read` 工具、能读文件、能调用生成 API，都不证明宿主可接收图片。
+
+- 宿主明确具备对应视觉输入能力时，使用其看图/视频工具检查实际成品。
+- 宿主是纯文本，或视觉能力没有可靠声明时，不把图片或视频帧直接塞进原生 Read
+  的图片返回通道。若有已授权的视觉分析工具，或同一消费主体下已授权、已准入且
+  收费路径不变的视觉模型，
+  可经 `arkcli-chat` / `arkcli-understand` 分析媒体并把**文字结果**返回当前宿主；
+  按对应 Skill 做 resources/Key/模型准入，不为验收自动换宿主模型、Profile 或 Key。
+- 没有兼容且已授权的视觉入口时，仍完成文件/解码/尺寸/时长等结构检查并交付成品，
+  明确哪些语义未验，不能声称看过。CI、远端无桌面环境不依赖 `--open` 来验收。
+- 生成已成功、后续宿主看图失败，是验收/交付链路失败，不是生成任务失败；保留已有
+  成品，不因此重提生成或轮转业务 Key。
+
+1. **执行**：真实 CLI 非错误响应；图片 status=succeeded；视频轮询读 `.status.phase`，
+   queued/running 不是成品，failed/cancelled 立即停止并说明。
+2. **交付**：逐一核对返回文件实际存在、可解码、文件数量、尺寸/比例、视频时长与所需音轨。
+   生成成功但下载失败，分别报告两项状态；优先用 CLI 已返回的本地文件，不重提任务。
+3. **语义**：用宿主可用的看图/视频能力检查上述清单。图片逐张检查；视频至少检查覆盖开头、
+   中间、结尾的时序证据，涉及运动/镜头/事件次序时不能只看首帧。抽帧不能证明音频要求。
+   不能把文件名、prompt、HTTP 200 或 Agent 自己的文字声明当作语义证据。
+4. **报告**：区分“已确认”“存在偏差”“未能验证”。没有查看成品就不能说逐项符合。
+   宿主不能看媒体时，仍交付文件并明确未验部分。`--open` 打开文件不等于验收通过。
+
+出现偏差时，保留原始成品；用户已授权迭代则针对失败项做有界修订，再验证未要求改变的部分。
+不无限重抽直到挑出一张好图后隐藏失败记录，也不把审美偏好当成确定性错误。
+
+可读回归场景见 [evals.md](evals.md)；自动门禁由独立 arkcli-eval-kit 维护。

package/skills/arkcli-helper/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: arkcli-helper
+version: 1.1.5
+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 配置。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli helper mcp --help"
+---
+
+# arkcli helper —— 给本机 AI Agent 配置 Plan / Platform Endpoint / 注入 MCP
+
+**前置:** 先用 Read 读 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) 获取共享安全规则与认证闸门。
+
+**CRITICAL — `arkcli helper` 整个命令域不支持 `--dry-run`。** Helper
+面向 TTY/本地 harness 配置，不是 API request preview。任何 helper
+命令带 `--dry-run` 都应 fail-fast 为 unknown flag；Agent 不得生成该
+组合，也不得把它当作写操作保护。真实 `configure/reset/mcp/supabase`
+仍必须先展示目标与路径并取得明确确认。
+
+## 命令选择（先选最具体的子命令）
+
+- 普通 Helper 准入从 `arkcli helper list` 和用户指定的目标开始；不要为补齐上下文自动执行 `profile show/list/keys list`。这些 Profile 命令可能在线同步并回写 Key，只有用户显式要求 Profile 管理时才进入，并先说明影响。
+- 用户要查看或配置 Agent 的 model/provider、Plan、Platform Endpoint，或核对 `--with-mcp` / `--with-supabase` / `--with-routing` 等非交互选项时，必须选择 `arkcli helper configure`；只查看用法也要运行 `arkcli helper configure --help`，不能退化成父级 `arkcli helper --help`。
+- 用户只要 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`。
+- Helper 配置 Agent Plan 时只能使用该 profile 的专属/席位 Key，不能用普通 API Key 池兜底。个人版专属记录存在但非 Active（如 `Restricted`）时，真人 TTY 会先说明轮转将立即使旧 Key 失效并询问；确认后只轮转一次、最多读 3 次状态，第一轮 Active 即停止。无专属记录、用户拒绝或非 TTY 时不轮转；失败引导必须去 Agent Plan 使用配置页，不能去普通 API Key 页面或 `auth apikey`。
+- `arkcli-auth` 只处理实际认证阻塞。用户仅要求查看 helper 的 `--help` 时，不要转去登录、`init-volc` 或其他认证命令。
+
+## 适用场景 / 唤起信号
+
+- 用户要给本机 Claude Code / Codex / OpenCode / OpenClaw / Hermes / ZCode 配置 Plan 或 Platform Endpoint 的 model/provider。
+- 用户要给支持的目标 Agent 配置豆包搜索、专业数据集或 OpenViking MCP，只安装云电脑 CUA Skill，或配置 byted-supabase。
+- 用户询问 `arkcli helper` 的安装态、配置态、文件落点、重载方式或 Agent Plan Harness 抵扣/超额后付费矩阵。
+
+## 反唤起信号 / 不该唤起
+
+- 只查询/购买/续费套餐或管理团队席位时转 `arkcli-plans`。
+- 只搜索基础模型、查询用量或价格时分别转 `arkcli-models`、`arkcli-usage`、`arkcli-pricing`。
+- 把 arkcli 内嵌 Skills 安装到 Agent 时转 `arkcli-connect`；不要把“安装 arkcli skill”误判为配置 Harness。
+- 仅排查登录、401 或 profile 覆盖问题时转 `arkcli-auth` / `arkcli-config`，不要反复重写 Agent 配置。
+- 用户问 **CC Switch / cc-switch 图形界面里如何选豆包、添加供应商或填写模型槽位**，而非要求 ArkCLI 修改本机 Agent 配置时，不走 `helper configure`；转 [`arkcli-docs`](../arkcli-docs/SKILL.md) 查官方 Claude Code/CC Switch 接入正文。按用户实际套餐区分 Key、Base URL 与 Model Name；套餐当前可用模型要以实时查询为准，认证失败时只给标明来源的文档示例，不能冒充实时清单。
+
+## TTY Harness 能力矩阵（Agent Plan / Agent Plan Team）
+
+真人直接运行 `arkcli helper` 时，向导顺序固定为：选择 Agent Plan profile → 选择模型 → 选择 AI Agent → 写入 model/provider → 进入 Harness 能力选择页。每行同时显示：
+
+1. 本次是否重新配置（`[✓]` 已选、`[ ]` 未选、`[-]` 当前不可配置）；
+2. 套餐抵扣是否开启；
+3. 超额后付费是否开启；
+4. 当前所选 AI Agent 的本地配置状态。
+
+本次选择与当前状态互相独立：默认勾选全部可配置能力；已显示“已配置”的能力进入下一步后仍必须重新执行配置。仅远端能力、当前 Agent 不支持以及团队版不提供的 Agent 记忆显示 `[-]`，不能选择。用户可取消任意能力；全部取消后选择“进入配置”会被阻止，也可以显式选择“跳过能力配置”。
+
+已知本地适配是精确映射，不按服务端名称做模糊猜测：
+
+| Harness 能力 | 本地交付形态 | “已配置”的判定 |
+|---|---|---|
+| 专业数据集 | MCP | `dataPro-search` 已注入且使用真实 Plan Key |
+| 豆包搜索 | MCP + Skill | 搜索 MCP 使用真实 Plan Key、`byted-web-search` Skill 已安装，且 Skill 根目录 `.env` 中存在可用的 `WEB_SEARCH_API_KEY` |
+| Agent 记忆 | MCP | OpenViking control-plane 已注入且使用真实 Plan Key |
+| AI Native 应用开发底座 | CLI + Skill | byted-supabase CLI、Skill、`ark_login` Agent Plan 登录态均就绪 |
+| Agent 进化 | CLI + Skill | 官方 Evolve CLI、`evolve-setup` Skill、workspace 配置与凭证均就绪 |
+
+服务端目录是远端权益状态的事实源：上面五个已知能力始终显示；当前套餐未返回映射时标明无远端权益、不开启远端切换，但仍可查看或补充本地配置。服务端新增但 arkcli 尚未适配的 Harness 显示在已知五项之后，标为“仅远端能力”，只允许查看/切换服务端权益，不提供猜测性的本地配置动作。
+
+- 个人版直接管理账号开关。
+- 团队版普通成员管理当前席位；管理员同时有席位时默认当前席位，也可选择企业账号范围。账号总闸关闭时，席位开关显示未开启并在详情中解释上级限制。
+- 开启超额后付费属于真实计费写操作：CLI 必须展示确认文案，默认选“取消”。服务端下发协议/购买链接时一并展示。不得用 `--dry-run` 代替确认。
+- Agent 进化只检测官方安装布局；当前不会自动执行未固定版本的远程 `latest/install.sh`，详情页提供官方命令让真人手动执行后刷新。
+- 豆包搜索 Skill 下载期间持续显示 Spinner；真人可按 `Ctrl+C` 立即取消当前下载并只跳过豆包搜索剩余配置。此时已注入的搜索 MCP 保留，不写 Skill 凭证、不修改原生 WebSearch，并继续配置本次已勾选的 Agent 记忆等后续能力。该按键只属于 TTY 矩阵，不改变非交互命令语义。
+- 强制路由只在能力配置完成后确认。Helper 从磁盘重新检测真实 Provider，动态列出可授权能力；零 Provider 时只能返回继续配置或不启用退出，不能安装空授权路由。
+- `helper configure/mcp/supabase/list/reset` 的非交互契约不因矩阵改变；Agent 自动化仍应选最具体的子命令，不得尝试操纵 TTY 菜单。
+
+## Agent Plan 强制检索路由（配置与运行时协议）
+
+本 Skill 负责分类与调用协议；真正的强制性来自 Helper 安装到 Harness 的 `UserPromptSubmit` / `PreToolUse` gate。它为每轮注入新的 `turn_id`，并在受管 Provider 执行前阻断错误或未授权 Provider。原生 WebSearch、WebFetch、WebExtract 不属于受管 Provider，不进入该 gate。
+
+仅 Volc `agent-plan` / `agent-plan-team` 与正式支持的 Claude Code、Codex、OpenCode、OpenClaw 可配置：
+
+```bash
+arkcli helper configure <claude-code|codex|opencode|openclaw> \
+  --profile <agent-plan-profile> \
+  --with-routing
+```
+
+`--with-routing` 隐含业务 MCP；Supabase 必须显式加 `--with-supabase`，且只有真实配置成功后才进入 Provider 集合。Hermes/Trae 缺少可验证的 hook + MCP 闭环时必须失败且保持 Harness 配置不变；Platform、Coding Plan 与非 Volc 产品不支持。
+
+上下文出现 `ARKCLI ROUTING ENFORCEMENT (routing.v1)` 时，每轮必须：
+
+1. 原样读取本轮 `turn_id` 与 `Available providers`，不得伪造或复用上一轮 ID。
+2. 把混合问题拆成可验收 task，并按固定映射选择唯一 Provider：`latest_public_web -> doubao_search`、`structured_dataset -> datapro`、`persistent_knowledge -> openviking`、`application_data -> supabase`、本地计算或需澄清 -> `none`。
+3. 在任何受管业务 Provider 前恰好调用一次 `arkcli-agentplan-search-router.submit_route_plan`，提交完整 `routing.v1` 计划；只调用原生 Web 工具时不提交计划。
+4. 计划接受后只调用已授权且真实可用的 Provider；正确 Provider 不可用时说明缺失并等待用户重新配置，不得 fallback。
+
+总领 Skill / 当前 Agent 负责理解用户意图，`arkcli-agentplan-search-router` 只接收计划并由 gate 执行授权，不是搜索服务，也不自行读取 Prompt。选择豆包搜索、DataPro、OpenViking 或 Supabase 时才进入 `routing.v1`；用户明确要求原生 WebSearch/WebFetch/WebExtract 时可直接调用，它们不消耗也不继承受管 Provider 授权。
+
+豆包搜索的同 Provider 入口顺序固定：已加载时优先调用 `byted-web-search` Skill；Skill 未安装、用户明确要求 MCP，或 Skill 在**业务请求发出前**因本地命令/配置错误失败时，保留原始错误并只改用一次 `mcp-server-askecho-search-infinity`。业务请求已经发出后出现鉴权、超时或服务错误必须停止，不得换入口重试。不得自行提取、打印或向工具手工传递 API Key。
+
+受管 Provider 之间禁止互相替代、先调用后补计划，也不得把路由 MCP 当作搜索 Provider。原生 WebSearch/WebFetch/WebExtract 位于该约束之外；但用户明确指定某个受管 Provider 时，不得在其失败后静默换成原生工具。Route Plan schema、混合请求与授权生命周期见 [`references/arkcli-helper.md`](references/arkcli-helper.md#routingv1-强制检索路由协议)。
+
+`helper mcp` 是**不改模型的非交互 Harness 工具入口**。不传 `--capability` 时保持存量整组 MCP 行为：个人版 `agent-plan` 注入四台，团队版 `agent-plan-team` 只注入豆包搜索 + DataPro。传 `--capability` 时只配所选单项，不带入其他已开启工具。
+
+## Platform Endpoint 配置
+
+Platform profile 只负责配置 Agent 的 model/provider：`model` 写为用户选择的 Endpoint ID，base URL 使用 Platform 的 `/api/v3`，协议继续由各 harness 保持现有行为（Chat 或 Responses）。
+
+- 只展示**当前 SSO 子用户创建**、`Running`、模型被明确验证为**文本输出**的 Endpoint；VLM（图文输入、文本输出）可用。
+- 生图、生视频、生 3D、音频、Embedding、内容生成或未知模型一律不展示，也不能通过 `--model` 绕过。
+- Agent 配置中的 `model` 仍写 Endpoint ID；context window、max completion tokens、输入/输出模态按 Endpoint 绑定的基础模型名，复用 Agent Plan / Coding Plan 现有的 ArkModels 元数据富化规则（ArkModels 权威数据优先；查不到或字段为零时用内置 Plan 模型能力表兜底，仍未知才省略扩展字段并在 helper configure 输出中提示）。元数据查询失败同样 best-effort，不阻断已通过资格校验的 Endpoint。
+- Hermes Agent 支持把 Platform Endpoint 写成 `volcengine-platform` model/provider；仍不支持 MCP 注入。
+- 该接入只为 Platform 增加元数据调用方，不修改 Plan 模型清单、默认模型、元数据查询、MCP 或 Supabase 行为。
+- 没有自己创建的 Endpoint 时，向导打开 `https://ark.volcengine.com/region:cn-beijing/endpoint/create?agentMode=close`；创建完成后选择“刷新列表”。已有但未运行的 Endpoint 需先启动再刷新。
+- Platform **不支持** MCP、OpenViking、Supabase 或强制路由；`--with-mcp`、`--with-supabase`、`--with-routing` 会报错。
+
+非交互调用：
+
+```bash
+arkcli helper configure codex \
+  --profile <platform-profile> \
+  --endpoint <ep-id>
+```
+
+配置成功后，Endpoint 可按 OpenAI 兼容入口调用：`/responses` 或 `/chat/completions`，请求的 `model` 均使用该 `<ep-id>`。
+
+## 注入的是哪几台 MCP(写死,勿幻觉)
+
+| server | 传输 | key 来源 |
+|--------|------|---------|
+| `mcp-server-askecho-search-infinity`（豆包搜索） | stdio(`uvx`) | **Agent Plan 的 API Key**(env `ASK_ECHO_SEARCH_INFINITY_API_KEY`,与 dataPro / 控制面**同一把** plan key);取不到则写占位符 |
+| `dataPro-search` | http(streamable) | **Agent Plan 的 API Key**(header `X-Agent-Plan-Key`,裸 key) |
+| `openviking-dataplane`（**仅个人版 agent-plan**） | http(streamable) | **OpenViking 库的访问 key**（数据面；header `Authorization: Bearer <key>`）;经 vikingdb 两步取:列库 → 按库取 key。账号多库时要选库(见下)。账号下 0 个库时跳过 |
+| `openviking-controlplane`（**仅个人版 agent-plan**） | stdio(`uvx`) | **Agent Plan 的 API Key**（控制面；env `AGENTPLAN_API_KEY`）;不依赖 OV 库列表,个人版有 Agent Plan 即注入 |
+
+> **个人版 vs 团队版:** 上表 OpenViking 两台是**个人版 `agent-plan`** 专属。**团队版 `agent-plan-team` 与 OpenViking 无关** —— 只注入豆包搜索 + dataPro 两台,`openviking-dataplane` / `openviking-controlplane` 都不配,也不会去查 vikingdb。
+
+## 豆包搜索成功后的原生 WebSearch 选择
+
+仅当豆包搜索 MCP 被选择、`byted-web-search` Skill 安装成功，且所选 Agent Plan 的同一把 API Key 已写入 Skill 根目录 `.env` 的 `WEB_SEARCH_API_KEY` 后，`helper` 才处理目标客户端的原生 `WebSearch/web_search`。TTY 会让用户选择“关闭（推荐）/保留”；非交互命令默认关闭，传 `--keep-native-websearch` 时保留。普通 model/provider 配置、Platform、Coding Plan、显式跳过豆包搜索、MCP 注入失败、Skill 安装失败或 Skill 凭证写入失败都不触发。Helper 不修改第三方 Skill 源码，也不得打印该 Key。
+
+- 范围严格限定为 `WebSearch/web_search`；**不会**关闭 `webfetch`、`web_extract`、`x_search`、浏览器或其它工具。
+- 项目级配置从当前目录向上寻找 `.git`（worktree 的 `.git` 文件也支持）；找不到时使用当前目录。
+- 配置成功后命令立即输出：客户端、作用域、配置路径，以及 `arkcli helper reset <harness>`。该 reset 是**完整回滚**，会同时移除 ArkCLI 写入的 model/provider/MCP，不是“只恢复搜索”。
+- ArkCLI 只恢复自己拥有且未被用户再次修改的字段。用户原本已经关闭搜索时不接管；配置后同一字段被外部修改时，reset 保留用户当前值并警告。
+- TRAE 写入 `.trae/hooks.json` 后，还必须在 `TRAE Settings > Hooks` 中启用当前项目；命令会明确提示“待激活”，不得宣称仅写文件就已生效。
+
+## host ≠ target(最关键的概念)
+
+- **host** = 你(这个 AI Agent)此刻跑在哪 —— 命令读环境变量自动检测,无需你判断。
+- **target** = 要把 MCP 写进谁的配置 —— 可以是 host 自己,也可以是另一个 agent。
+- 二者解耦:人在 OpenCode 里,也能给 Claude Code 配 MCP。
+
+→ 用户在 prompt 里**点名了某个 agent**(如"给 opencode / codex 配"):跑 `arkcli helper mcp opencode` / `arkcli helper mcp codex`
+→ 用户说"**当前 / 这个 Agent**"或没点名:跑 `arkcli helper mcp`(自动检测当前 host)
+
+## 子命令穷举
+
+| 调用 | 说明 |
+|------|------|
+| `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 |
+| `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。 |
+| `arkcli helper list` | 查支持的 agent + 安装/配置状态(只读) |
+| `arkcli helper supabase [--profile P]` | **非 MCP**:装 byted-supabase-cli + skill + 注入火山登录态(打通 byted-supabase 数据库能力);跟 harness 无关。仅 Agent Plan(个人版全档 + 团队版全档) |
+| `arkcli helper reset <harness>` | 完整移除 arkcli 注入的 model/provider/MCP/托管路由 hook/tool/plugin，并恢复 ArkCLI 拥有且未被外部修改的原生搜索字段 |
+| `arkcli helper` | TTY 交互向导(需终端;非交互场景改用上面的);进入向导前会检查登录态,未登录/SSO 过期时按当前登录上下文拉起 SSO(火山走 volc-sso;全新用户无明确上下文时走 auth login 菜单),成功后继续向导；Agent Plan/Team 按 profile→model→Agent→能力多选→逐项配置推进，随后只基于已验真的真实 Provider 动态确认强制路由 |
+
+> ⚠️ 想"只加 MCP" → `helper mcp`;想"把 agent 接到 plan、连模型一起" → `helper configure --with-mcp`。别用 `configure` 去只加 MCP(它会一并(重)写 model)。
+>
+> 🎯 用户说"**把(我 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 配置)。
+>
+> 🧭 用户明确要“强制受管 Provider 路由 / routing.v1 / 防止豆包搜索、DataPro、OpenViking、Supabase 串路由”→ 使用本 Skill 的“Agent Plan 强制检索路由”协议，并执行 `helper configure <harness> --with-routing`。该 flag 隐含业务 MCP；Supabase 仍需显式加 `--with-supabase`，原生 Web 工具不受此 flag 管理。
+
+## byted-supabase 数据库能力(`helper supabase`;**非 MCP**)
+
+`arkcli helper supabase` 跟上面的 MCP 注入是**两类能力**:它**不写** agent 的 mcp.json,而是**装 byted-supabase-cli + skill** 并用当前火山 Agent Plan 登录态**注入登录态**(打通 byted-supabase / Volcengine Supabase 数据库平台)。**跟选哪个 harness 无关** —— 它配的是 byted-supabase-cli 这个独立工具本身。
+
+- **门槛**:仅 Agent Plan —— 个人版 `agent-plan` **全档**支持(含 small/medium/large/max),团队版 `agent-plan-team` **全档**支持。不合格命令直接报错说明。
+- **动作**:装 CLI(`npx -y @byted-supabase/cli@latest install`,连匹配的 byted-supabase agent skill 一起)→ 用所选 Agent Plan 身份的 STS + refresh_token 组装 Console Login 凭证 → `byted-supabase-cli login --credential-file`(个人版带 `--is-agent-plan`,团队版额外 `--agent-plan-seat-id <实时反查>`)注入到固定 profile `ark_login`。
+- **触发**:用户说『配 byted-supabase / 打通数据库 / 装 supabase cli / 连接 supabase / 用我的 plan 连数据库』。
+- **三条配置入口**(同一内核 `supabase.Configure`):① 专配 `arkcli helper supabase`;② 非交互/agent 顺带配 `arkcli helper configure <h> --with-supabase`(无确认框、失败只 warn,不阻断 harness 配置);③ 交互向导 `arkcli helper` 末尾可选步骤(仅合格 plan)。`helper mcp` / `configure --with-mcp` **不含** Supabase —— 想顺带配必须显式 `--with-supabase`。
+- ⚠️ **v3 ve handoff 身份 (source=ve) 不能配 supabase**: `helper supabase` 内核 `gatherInputs` 强依赖 `LoadIdentityTokenFull(key)` 读 identity_store `token.json` 里的 refresh_token 组装 Console Login 凭证; 而 source=ve 身份**不落 token.json** (refresh_token 由 volcengine-go-sdk 内部管, arkcli 侧拿不到明文), 会报 `读 identity token: ...`。命中该报错时告诉用户: 想配 supabase 需要走 arkcli 原生 SSO 登录一次 (跳过 ve handoff), 具体做法是先 `ve logout` (或让 `ve` 处于未登录态) 再跑 `arkcli auth login` 拿到 `source="arkcli"` 的 identity。
+
+## 范围边界(管好,别越界)
+
+- **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。
+- **可注入 MCP 的 target 有 8 个**:`claude-code` / `codex` / `opencode` / `openclaw` / `trae` / `deepseek-harness` / `zcode` / `workbuddy`。CUA 是 Skill 而非 MCP，还可精确安装给 `hermes` / `pi`；命令只传单个 target，不扫描或改动其他 Agent。
+- 本 skill 会被 `arkcli +connect` 装进很多 agent(cursor / gemini-cli / codex …40+),但 **MCP 注入只支持上一条列出的 8 个 target**。host 是其它 agent 时:要么用户点名其一作 target,要么命令会报"请显式指定" —— **绝不静默配错对象**。
+- `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 共享读取。
+- `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` 启用当前项目。
+- `hermes` 支持 Plan / Platform Endpoint 的 model/provider 配置，但暂不支持 MCP 注入 → MCP 请求命中就直说"暂不支持"。
+- `deepseek-harness` (DSH):默认 home scope，可直接运行 `arkcli helper configure deepseek-harness --profile <plan>` 或 `arkcli helper mcp deepseek-harness`；若要写 profile scope，传 `--dsh-config-scope profile --dsh-profile <name>`，Helper 会确保 profile 目录存在。DSH provider/模型配置落到 `$DSH_HOME/settings.yaml` 的 `llm-pi-ai.providers.arkcli-<planType>:` 段（独立 provider,**不覆盖** `llm-deepseek:` 下的 DeepSeek 官方模型;用户可在 DSH 里切换官方 DeepSeek 与 arkcli 火山模型）；默认模型写 `agent-default-model:`;API key 写入 `$DSH_HOME/.credentials.yaml` version 1 文档的 `refs.ARKCLI_<PLAN>_API_KEY`，由 DSH credentials service 按 `apiKeyEnv` 解析（不覆盖用户的 `DEEPSEEK_API_KEY`）。这是 breaking change：检测到旧版 ArkCLI 的 `llm-deepseek:` 指纹、纯 flat credentials，或 version 1 文档顶层残留的 legacy credential key 时，`configure` 不自动迁移，而是拒绝写入并要求先运行 `arkcli helper reset deepseek-harness`；`reset` 兼容清理这些旧格式，但任意自定义 `apiKeyEnv` 仍视为用户配置。settings 与 credentials 作为一个可回滚事务更新；`reset` 只删除仍保持 ArkCLI provider fingerprint 的条目、对应凭据以及仍指向它的默认模型。MCP / 原生 WebSearch 关闭落在 `$DSH_HOME/profiles/<name>/cordis.patch.yml`(profile scope)或 `$DSH_HOME/cordis.patch.yml`(home scope)。DSH 不导出 env marker,`helper mcp` 不传 target 不会自动选 DSH。原生 WebSearch 用 patch 层对 `@deepseek-ai/dsh-tool-web` 加 `disabled: true`(trae 风格 hook 兜底,精确作用当前 profile,reset 时按 marker 还原)。
+- `pi`(minimal terminal coding harness,`npm i -g --ignore-scripts @earendil-works/pi-coding-agent`)支持 Plan / Platform Endpoint 的 model/provider 配置,但**没有原生 MCP host 能力** → DataPro / 豆包搜索 / Agent 记忆请求命中就直说"暂不支持"。`helper mcp pi --capability cua` 是例外，因为 CUA 只安装 Skill、不注入 MCP；仍受个人版 Medium/Large/Max 资格闸约束。provider/模型清单写 `~/.pi/agent/models.json`(openai-completions provider,键=plan type),默认 provider/model 写同目录 `~/.pi/agent/settings.json` 的 `defaultProvider` / `defaultModel`(bare model id);目录可被 `$PI_CODING_AGENT_DIR` 覆盖。
+- `zcode` 支持 Plan / Platform Endpoint 的 model/provider 配置与 MCP 注入。模型配置写 `$ZCODE_HOME/v2/config.json`（默认 `~/.zcode/v2/config.json`）；ZCode 不会热加载 provider registry，配置后必须完全退出 ZCode 主进程、重新打开并新建会话，不能只切模型或复用旧会话。遇到 Coding Plan `InvalidParameter` / token 上限 400 时不要手改某个模型的固定值，重新运行 `helper configure zcode`，由 Helper 优先使用套餐模型接口的 `ModelCapability` 写入 `limit.context`，并把 `limit.output` 转成方舟网关接受的十进制 token 上限；详见 reference。
+- `workbuddy`(CodeBuddy IDE,VSCode 系):同时支持 model + MCP,**无运行态宿主检测**(不会被自动当成 host),只能显式 `arkcli helper configure workbuddy` / `arkcli helper mcp workbuddy`。model 与 MCP 同时写入**三个落点** `~/.workbuddy-ai/`(IDE 真正读取的运行态目录)、`~/.workbuddy/` 与 `~/.codebuddy/`:model 清单进各自 `models.json`(OpenAI 兼容,`url` 为含 `/chat/completions` 的完整路径,arkcli 写入项打 `arkcliManaged` marker 供精确 reset),MCP 进各自 `mcp.json`(`mcpServers.*`,schema 与 claude-code 同构)。**不支持原生 WebSearch 关闭**(无 hook seam),豆包搜索配置只注入 MCP、不接管原生搜索。
+- 强制路由正式支持 `claude-code` / `codex` / `opencode` / `openclaw`；Hermes/TRAE 走能力门禁，缺 hook + MCP 闭环时零 Harness 配置写入并报错，不做提示词降级。
+- Plan 的 model 可以配成路由模型 `ark-code-latest`(交互向导会先问「智能路由 (ark-code-latest) vs 指定具体模型」;非交互直接 `--model ark-code-latest`)。指定具体模型时，候选必须来自套餐 VirtualModelID 清单，对应 `plans model-list --mode direct` 的 `direct_models[].model_name`；不能把 LatestModel 路由候选的 `models[].output_name` 当作直接 ModelName。**切换 ark-code-latest 的路由目标(Auto 智能调度 / 锁定某个底层模型)不在本 skill** —— 走 `arkcli plans model-apply --plan <plan> --model <目标>`(见 [`../arkcli-plans/`](../arkcli-plans/SKILL.md)),写控制面、与控制台联动。交互列表仅在服务端负载 `status=1` 且 `level=1/2/3` 时显示低/中/高负载。
+
+## 前提
+
+- **必须有 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。
+- 注入后 **agent 需重启**才会加载新 MCP。Codex profile 模式还需用 `codex --profile <name>` 启动;Trae 还需去「设置 → MCP」面板确认 MCP 已启用(项目级文件额外要开「启用项目级 MCP」开关)，并在 `Settings > Hooks` 启用当前项目后重开项目。
+
+## OpenViking 库的选择(openviking-dataplane 专属;**仅个人版 agent-plan**)
+
+> 本节只适用于**个人版 `agent-plan`**。**团队版 `agent-plan-team` 与 OpenViking 无关**,命令对团队版直接跳过下面整套列库/选库流程,只注入豆包搜索 + dataPro。
+
+`openviking-dataplane` 的 key 绑定到某个 OpenViking 库(库名 ↔ ResourceID 1:1)。命令先列账号下的库,按数量分流:
+
+- **0 个库** → 自动跳过 openviking-dataplane(仍注入另三台,包括 openviking-controlplane),并提示去 `https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing/create` 建库后重跑。可直接接受跳过。
+- **1 个库** → 直接用,无需选择。
+- **多个库** → 命令报错并列出所有库名(形如 `检测到多个 OpenViking 库,请用 --ov-resource <库名> 指定其一:[a, b, c]`)。把这次错误中返回的真实库名交给宿主提供的结构化选择能力；不要写死某个宿主工具名，也不要凭记忆补库。拿到选定库名后带 `--ov-resource <库名>` 重跑同一条命令；宿主没有结构化选择能力时退化为精简编号列表。
+- 取 key 失败(非 0 库)→ openviking-dataplane 写占位符 `Bearer <OPENVIKING_KEY>`,提示用户手动替换。
+- `openviking-controlplane` 不受上述影响:个人版只要有 Agent Plan 就始终注入(团队版不注入,见上)。
+
+## 路由判断 / 反触发
+
+- "给 Agent 配 MCP / 豆包搜索 / 联网搜索 / dataPro / web search" → `arkcli helper mcp`
+- "只给 Codex 配某一项 Harness 能力" → `arkcli helper mcp codex --capability <datapro|web-search|agent-memory>`；只配云电脑 → `arkcli helper mcp codex --capability cua`
+- "把 agent 指向我的 plan(连模型一起)" → `arkcli helper configure`
+- "打开 helper 看 Harness 抵扣/超额开关和本地配置矩阵" → 真人 TTY 运行 `arkcli helper`；Agent 不自动驾驶该菜单
+- "把全套 harness 工具都配上 / 一次配齐 MCP + Supabase" → `arkcli helper configure <h> --with-mcp --with-supabase`
+- "启用强制受管 Provider 路由 / routing.v1 / 防止豆包搜索、DataPro、OpenViking、Supabase 串路由" → 使用本 Skill 的强制检索路由协议，执行 `arkcli helper configure <h> --with-routing`
+- "配 byted-supabase / 打通数据库 / 装 supabase cli / 连接 supabase" → `arkcli helper supabase`(非 MCP,装 CLI+skill+注入登录态);或在配 harness 时顺带 `configure --with-supabase`
+- 把 arkcli skills **安装**进 agent → 走 [arkcli-connect](../arkcli-connect/SKILL.md),与本 skill 无关
+- 401 / 登录 / 鉴权失败 → 走 [arkcli-auth](../arkcli-auth/SKILL.md)
+- 生图 / 生视频 → 走 [arkcli-gen](../arkcli-gen/SKILL.md)
+
+详细 flag、输出样例、错误码、边界 case 见 [`references/arkcli-helper.md`](references/arkcli-helper.md)。
+
+## References / 详细参考
+
+- [`references/arkcli-helper.md`](references/arkcli-helper.md)：完整 flag、MCP/Skill/CLI 落点、Harness 矩阵状态机与错误处理。
+- [`references/evals.md`](references/evals.md)：Trigger、反触发、写操作守卫和回归用例。
+- [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)：所有 arkcli Skill 共用的认证、输出与安全约束。