@tencentcloudadp/cli 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloudadp/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "CLI for Tencent Cloud Agent Development Platform (ADP)",
   "type": "module",
   "bin": {
@@ -36,6 +36,7 @@
     "test": "vitest run",
     "test:unit": "vitest run tests/unit",
     "test:integration": "vitest run tests/integration",
+    "check:portable": "pnpm lint && pnpm typecheck && node scripts/architecture-check.mjs && node scripts/check-esm-imports.mjs && node scripts/check-secrets.mjs && pnpm knip && pnpm build && pnpm test:unit && pnpm test:integration && pnpm workbuddy:connector && node scripts/smoke-cli.mjs",
     "eval:cli": "vitest run tests/integration/cli/agent-contract.test.ts tests/integration/cli/agent-eval.test.ts tests/integration/cli/agent-grader.test.ts",
     "eval:grade": "tsx scripts/grade-agent-eval.ts",
     "knip": "knip"

package/skills/adp/SKILL.md

@@ -58,7 +58,7 @@ adp schema --command "channel" --compact --format json
 
 | 当前任务 | 读取 |
 | --- | --- |
-| 创建应用（含从模板创建）、选模式、知识库导入、工作流与异步试跑、应用/工作流包导入导出 | [create/SKILL.md](create/SKILL.md) |
+| 创建应用、添加 Claw 子 Agent、选模式、知识库导入、工作流与异步试跑、应用/工作流包导入导出 | [create/SKILL.md](create/SKILL.md) |
 | 修改 adp.jsonc、环境覆盖、同步草稿 | [configuration/SKILL.md](configuration/SKILL.md) |
 | 发布、模式限制、挂载插件或 Skill | [gotchas/SKILL.md](gotchas/SKILL.md) |
 | 平台 Skill 发布、引用方、分类、共享到企业技能中心 | [references/platform-skills.md](references/platform-skills.md) |
@@ -66,7 +66,8 @@ adp schema --command "channel" --compact --format json
 | 盘点应用、翻页、统计会话 | [references/inventory.md](references/inventory.md) |
 | 绑定或发布报错、全量覆盖字段 | [references/pitfalls.md](references/pitfalls.md) |
 | 记忆库、记忆条目、用户摘要、应用绑定记忆库 | [references/memory.md](references/memory.md) |
-| 插件/连接器凭证、API Key、OAuth 授权、插件工具详情、插件跨空间共享 | [references/credentials.md](references/credentials.md) |
+| 插件/连接器凭证、OAuth 授权、工具密钥（ADP API Key：创建/启停/删除）、插件工具详情与跨空间共享 | [references/credentials.md](references/credentials.md) |
+| MCP 插件：直接调用平台 MCP 插件（如可灵）、实时工具列表、将导出的 MCP 插件装入 Coding Agent、注册外部 MCP Server | [references/mcp.md](references/mcp.md) |
 | 工作台定时任务（按调度跑 prompt）、运行日志 | [references/timers.md](references/timers.md) |
 | 云盘：上传下载文件、目录、挂载给应用 | [references/volumes.md](references/volumes.md) |
 | 取 AppKey（对话/分享用的应用密钥）、启停和删除 key、分享链接、分享会话、企业共享应用、A2A 地址 | [references/app-keys.md](references/app-keys.md) |

package/skills/adp/configuration/SKILL.md

@@ -37,6 +37,9 @@ adp schema --command dev --format json
 | Plugin tools | `agent.tools` (`plugin_id` + `tool_id`) |
 | Plugins / connectors | `agent.plugin_ids` / `agent.plugins` / `connector_ids` |
 | Skill mounts | `agent.skill_ids` (Claw only) |
+| Claw main agent | `agent` (`agent.profile.role` 0) plus top-level `agent_id` |
+| Claw sub-agents | not a second `agent` block; `adp agent create --role 1` |
+| Claw team collaboration | `mode.claw.team_enabled`, `mode.claw.team_prompt` |
 | Multi-agent collab | `mode.multi_agent.collaboration_mode` |
 | Bind an existing workflow | `mode.single_workflow.workflow_id` |
 

package/skills/adp/create/SKILL.md

@@ -50,7 +50,7 @@ adp init --name "<name>" --space-id "<space_id>" --model-id "<model_id>" \
   --app-mode <1|2|3|4> --create-remote --format json
 ```
 
-`--create-remote` calls `CreateApp`. **Claw (`4`)** then `CreateAgent` and writes `agent_id`. A Claw app has exactly one config-side agent: a second `adp agent create` fails with `AgentAlreadyExists` (ADP returns the existing id); edit it with `adp agent update` instead. Standard (`1`) / single-workflow (`3`) have no agent (`CreateAgent` is rejected). Multi-Agent (`2`) binds the first listed agent if the platform created one; a fresh Multi-Agent app usually has none, so `agent_id` stays empty and that is expected. Then `ModifyApp` (and `ModifyAgent` only when `agent_id` is set). For Standard, put the role in `role_description`, not only `instructions.md`: `adp init --app-mode 1` (and `3`) copies the instructions (an existing `instructions.md` included) into top-level `role_description`; edit that key afterwards. Creation consumes quota and is not easily undone from this CLI without `adp delete --yes`.
+`--create-remote` calls `CreateApp`. **Claw (`4`)** then `CreateAgent` for the main agent (`Role=0`) and writes `agent_id`. A Claw app has **1 main agent (`Role=0`) and up to 19 sub-agents (`Role=1`)**, 20 agents in total. Creating a second main agent fails with `AgentAlreadyExists` (ADP returns the existing id); edit that agent with `adp agent update`. Add a sub-agent with `adp agent create --role 1` (see [Agents after init](#agents-after-init)). Standard (`1`) / single-workflow (`3`) have no agent (`CreateAgent` is rejected). Multi-Agent (`2`) binds the first listed agent if the platform created one; a fresh Multi-Agent app usually has none, so `agent_id` stays empty and that is expected. Then `ModifyApp` (and `ModifyAgent` only when `agent_id` is set). For Standard, put the role in `role_description`, not only `instructions.md`: `adp init --app-mode 1` (and `3`) copies the instructions (an existing `instructions.md` included) into top-level `role_description`; edit that key afterwards. Creation consumes quota and is not easily undone from this CLI without `adp delete --yes`.
 
 Then publish only if they asked to 上线 / 发布:
 
@@ -78,7 +78,7 @@ Right after `adp deploy` the first call of a tool can fail on the runtime side (
 
 ## Knowledge-base documents
 
-Default KB id equals `app_id`. Same CAM keys; no extra COS or AppKey. Read it with `adp kb get --kb-id "<app_id>" --space-id "<space_id>"` (the platform's `DescribeKB` only serves shared KBs, so the CLI reads the default KB from the space's KB list and needs the space).
+Default KB id equals `app_id`. Same profile keys on the public cloud and the independent site; no extra COS or AppKey. Read it with `adp kb get --kb-id "<app_id>" --space-id "<space_id>"` (the platform's `DescribeKB` only serves shared KBs, so the CLI reads the default KB from the space's KB list and needs the space).
 
 ```bash
 adp kb doc import --file ./faq.md --format json --cwd "<project>"
@@ -101,13 +101,45 @@ A Claw agent only searches knowledge through the `KnowledgeRetrievalAnswer` tool
 
 ## Agents after init
 
-`adp agent create` is **Claw-only** (`app_mode 4`), and a Claw app holds exactly one config-side agent, so in practice it only re-creates the agent of a Claw app that has none:
+`adp agent create` is **Claw-only** (`app_mode 4`). A Claw app has **1 main agent (`Role=0`)** and up to **19 sub-agents (`Role=1`)** (20 agents total). `adp.jsonc` `agent` is the main agent. `adp dev` / `adp deploy` call `ModifyAgent` only for that `agent_id`; they do not overwrite sub-agents.
+
+`CreateAgent` with `Role=0` is idempotent once a main agent exists: a second `adp agent create` without `--role 1` returns `AgentAlreadyExists` (including `--dry-run`). The error `next_actions` include a runnable `adp agent create --role 1` preview. Edit the main agent with `adp agent update`.
+
+Add a sub-agent (this is how to handle “给这个应用添加子 agent，名字叫 …”):
 
 ```bash
-adp agent create --app-id "<claw_app_id>" --dry-run --format json
+adp schema --command "agent create" --format json
+adp agent create --app-id "<claw_app_id>" --role 1 --name "<name>" \
+  --description "<when the main agent should delegate>" \
+  --instructions "<how this sub-agent works>" \
+  [--model-id "<model_id>"] --dry-run --format json
+adp agent create --app-id "<claw_app_id>" --role 1 --name "<name>" \
+  --description "<when the main agent should delegate>" \
+  --instructions "<how this sub-agent works>" \
+  [--model-id "<model_id>"] --format json
+```
+
+`--sub-agent` is the same as `--role 1`. `--description` is the routing text the main agent uses to decide when to delegate. `--name` is required for a sub-agent (do not reuse the main agent's name from `adp.jsonc`). The same flags work with no `adp.jsonc` as long as `--app-id` is set. With `--role 1`, the CLI does **not** copy the main agent's `instructions.md`, `skill_ids`, or `plugin_ids`. Pass `--instructions` or `--instructions-file` for the sub-agent prompt; if you pass neither, the prompt is a short default from the name. Pass `--skill-id` only for skills this sub-agent should mount (default: none). Omit `--model-id` to inherit a real `adp.jsonc` model, else the main agent's model, else the first `ModelScene=18` model, else `Auto/auto`.
+
+Change a sub-agent without rewriting `adp.jsonc` by passing only the fields that change. The CLI reads the current agent and keeps the rest (including `Role`):
+
+```bash
+adp agent update --app-id "<claw_app_id>" --agent-id "<sub_agent_id>" \
+  --name "<name>" --description "<when to delegate>" --dry-run --format json
 ```
 
-On Standard (`1`), Multi-Agent (`2`) or single-workflow (`3`) apps the CLI reads the app mode first and refuses with a usage error, also under `--dry-run` (upstream would answer `560001`). Edit an existing agent with `adp agent update --app-id <id> --agent-id <id>`; for a separate agent, create another Claw app with `adp init --app-mode 4`.
+With no field flags, `adp agent update` still syncs `adp.jsonc` plus `instructions.md` onto `--agent-id`.
+
+Claw multi-agent collaboration (doc 134193) has two mechanisms:
+
+1. **单向委派 (default).** The main agent routes work to sub-agents from each sub-agent's `name` and `description`. Each sub-agent runs with its own `instructions`, model, skills, and tools.
+2. **团队协作 (optional).** Set `mode.claw.team_enabled` and `mode.claw.team_prompt` in `adp.jsonc` (`ClawAgentConfig.AgentTeamConfig`). Teammates can report back and talk to each other according to `team_prompt`. That is app config, not a substitute for creating the sub-agent.
+
+On Standard (`1`), Multi-Agent (`2`) or single-workflow (`3`) apps the CLI reads the app mode first and refuses with a usage error, also under `--dry-run` (upstream would answer `560001`). Edit an existing agent with `adp agent update`; for another Claw agent, create a Claw app with `adp init --app-mode 4`. Re-create a missing main agent (role 0) only when `adp agent list` shows no role 0 agent:
+
+```bash
+adp agent create --app-id "<claw_app_id>" --dry-run --format json
+```
 
 This CLI does **not** generate canvas JSON — copy a template from
 [../references/workflows.md](../references/workflows.md), export one, or pull one from an existing app. It can bind an existing id in `adp.jsonc`
@@ -117,8 +149,8 @@ This CLI does **not** generate canvas JSON — copy a template from
 
 ## Workflows
 
-`adp workflow` uses the same CAM keys as every other command (it calls LKE canvas
-actions). It is cloud-site only.
+`adp workflow` uses the same profile keys as every other command (it calls LKE canvas
+actions). Public cloud sends them to `lke.tencentcloudapi.com`; an independent or custom profile sends them to its ADP host.
 
 ```bash
 adp workflow list --app-id "<app_id>" --format json --fields workflowId,name,status,isEnable

package/skills/adp/evals/evals.json

@@ -55,6 +55,20 @@
         "没有写入尝试",
         "最终回答区分预览与已创建"
       ]
+    },
+    {
+      "id": 5,
+      "name": "claw-sub-agent",
+      "prompt": "给这个应用添加子agent，名字叫ray的测试agent。应用 ID 是 4004，这是一个已经有主 Agent 的 Claw 应用。先看 schema，再预览，确认后再创建。不要改主 Agent，也不要因为应用里已经有 Agent 就放弃。",
+      "expected_output": "按 create/SKILL.md 执行 adp agent create --app-id 4004 --role 1 --name ray的测试agent 的 dry-run，然后去掉 --dry-run 真正创建。结果是新的子 Agent，不是 AgentAlreadyExists。",
+      "files": [],
+      "assertions": [
+        "先读取 agent create 的 schema",
+        "用 --role 1 和名字 ray的测试agent 对应用 4004 做 --dry-run 且成功",
+        "去掉 --dry-run 后创建出新的子 Agent，且没有复制主 Agent 的 skill",
+        "role 1 的创建没有报 AgentAlreadyExists，也没有被适配器拦截",
+        "最终回答说明已添加名为 ray的测试agent 的子 Agent"
+      ]
     }
   ]
 }

package/skills/adp/gotchas/SKILL.md

@@ -30,7 +30,7 @@ Platform has two domains: **draft** (owner only) and **release** (end users). `M
 
 Claw cannot switch to or from 1/2/3 on the same app. Create a new app.
 
-`CreateAgent` is **Claw-only**. Standard (`1`) and single-workflow (`3`) have no agent. Multi-Agent (`2`) may bind an existing agent from `DescribeAgentSummaryList`. Standard instructions live in `role_description`, not only `instructions.md`.
+`CreateAgent` is **Claw-only**. A Claw app has one main agent (`Role=0`) and up to 19 sub-agents (`Role=1`). A second role 0 create returns `AgentAlreadyExists`; add a sub-agent with `adp agent create --role 1` (see [create/SKILL.md](../create/SKILL.md)). Standard (`1`) and single-workflow (`3`) have no agent. Multi-Agent (`2`) may bind an existing agent from `DescribeAgentSummaryList`. Standard instructions live in `role_description`, not only `instructions.md`.
 
 `app_mode` is not Multi-Agent **collaboration**. That is `mode.multi_agent.collaboration_mode` (1 free-handoff / 2 workflow / 3 Plan-and-Execute).
 
@@ -59,13 +59,13 @@ Full table: [../references/app-modes.md](../references/app-modes.md).
 - `adp app copy --target-space-id <id> --yes` copies an app; the copy is named "<name>的副本NN", so rename it with `adp app update` if the user cares.
 - Check what is bound with `adp agent resources --agent-id <id> [--type skills]`; quotas with `adp agent limits`.
 - Skill **mounts** are Claw-only (`agent.skill_ids`).
-- Child agents are agents, never tools. Do not put an `agent_id` in a plugin list.
+- Child agents are agents, never tools. Do not put an `agent_id` in a plugin list. On Claw, create them with `adp agent create --app-id <id> --role 1 --name "<name>" --description "<when to delegate>"`. `Role=0` is the one main agent.
 
 ## Knowledge
 
 An ID flag fed a name or non-numeric string fails with `InvalidIdFormat` (exit 2; the platform only says `invalid character … looking for beginning of value`). Use the numeric ID from the matching `list` command.
 
-Default KB id = `app_id`; read it with `adp kb get --kb-id <app_id> --space-id <space_id>`. `adp kb doc import` uses the same CAM keys; no extra COS or AppKey. Shared KBs, categories, labels, and QA are managed with `adp kb create`, `adp kb category`, `adp kb label`, and `adp kb qa`; check `adp schema --command kb --compact --format json` for flags. Bind a shared KB to an app with `shared_kb_ids` in `adp.jsonc`. To use a KB from another space, the owner runs `adp kb share set --space-id <owner_space> --kb-id <kb_id> --scope spaces --space <target> --yes`; read the current scope with `adp kb share get --space-id <owner_space> --kb-id <kb_id>` and check the target side with `adp kb share inbound --space-id <target>`. Both `kb share get` and `kb share set` need the owning space (`--space-id` or `adp.jsonc`). `kb share set` replaces the whole scope and is visible to everyone in the target spaces, so confirm the targets with the user; add `--request-approval --remark` only when the user wants admin approval.
+Default KB id = `app_id`; read it with `adp kb get --kb-id <app_id> --space-id <space_id>`. `adp kb doc import` uses the same profile keys on the public cloud and the independent site; no extra COS or AppKey. Shared KBs, categories, labels, and QA are managed with `adp kb create`, `adp kb category`, `adp kb label`, and `adp kb qa`; check `adp schema --command kb --compact --format json` for flags. Bind a shared KB to an app with `shared_kb_ids` in `adp.jsonc`. To use a KB from another space, the owner runs `adp kb share set --space-id <owner_space> --kb-id <kb_id> --scope spaces --space <target> --yes`; read the current scope with `adp kb share get --space-id <owner_space> --kb-id <kb_id>` and check the target side with `adp kb share inbound --space-id <target>`. Both `kb share get` and `kb share set` need the owning space (`--space-id` or `adp.jsonc`). `kb share set` replaces the whole scope and is visible to everyone in the target spaces, so confirm the targets with the user; add `--request-approval --remark` only when the user wants admin approval.
 
 Pagination: `--page` (0-based) works on page-numbered lists. Cursor lists do not take it: `adp audit list` refuses `--page` with a UsageError and continues with the `--cursor` value from its next action; `conversation messages` continues with `--record-id`. `adp docs search` continues with `--page` over the same ranked pool (`total` appears when the portal returned every hit).
 
@@ -73,9 +73,13 @@ Pagination: `--page` (0-based) works on page-numbered lists. Cursor lists do not
 
 `adp conversation list` returns sessions the current CAM key can see. It is not application-wide C-end volume. The result field `scope` is `owner`; there is no `--scope` flag. Without `adp.jsonc`, pass `--app-id` after `space list` and `app list --space-id`. Do not run `adp init` to list sessions. `adp conversation messages` reads one of those sessions. A `tool_call` row is the tool span: `trace.toolName`, `trace.traceId`, `title` (call), and content `text` (result). There is no separate thought document. `--type 0`, `5`, and `20` are refused; pass the `type` from the `conversation list` row. `adp conversation create|get|rename|reset|delete` default to `--type 2` (evaluation); pass `--type 1` for visitor sessions or you get `ConversationNotFound`. After `delete`, `get` answers `ConversationNotFound`; `reset` clears context but keeps history, and is a write: it needs `--yes` (without it the CLI refuses and the next action is the same command with `--yes`). `get` / `messages` / `reset` / `delete` accept `--app-id` (validated and echoed, not sent: these APIs take only the conversation ID). `adp chat` sessions are type 5 (API) and cannot be read back with `conversation messages`; next actions suggest `adp chat` only for type 1 conversations. `adp conversation record get --record-id` takes the question record ID from `conversation messages`, or the reply `recordId` from `adp tail` together with that row's `--conversation-id`. Rows from `adp chat` (API conversations) cannot be resolved that way. `adp app token sse|ws` print a masked token; add `--reveal` only when the caller must hand it to a channel client. `adp usage` is one app's model KPIs for the last 7 days and needs `--app-id` or `adp.jsonc`. It may fail with 450002 (no metric permission); then use `adp app list --fields appId,name,status,updateTime`.
 
+## 直接调用平台 MCP 插件
+
+平台插件 `pluginKind=2`（例如可灵）的地址是 `https://adp.cloud.tencent.com/plugin/mcp/<pluginId>/mcp`，鉴权是 ADP API Key（工具密钥），不是 CAM，也不是 `adp credential` 里的连接器凭证。先 `adp plugin key create`（默认写入 `~/.adp/tool-key`，权限 0600），再 `adp plugin tool call`。每个账号最多 2 把，超出报 `ToolKeyLimitReached`（`4509400`）；明文无法从列表取回，先 `adp plugin key list` 确认要删的闲置密钥。删除前必须先 `adp plugin key disable --key-id <id>`，再 `adp plugin key delete --key-id <id> --yes`；仍启用时删除报 `ToolKeyNotDisabled`（`4509404`）。`--dry-run` 没有本地密钥时也只返回预览（`hasKey: false`），不发请求。不要把密钥写进命令参数。MCP 调用与 Coding Agent 接入见 [../references/mcp.md](../references/mcp.md)，工具密钥与凭证管理见 [../references/credentials.md](../references/credentials.md)。
+
 ## 工作流边界
 
-`adp workflow` 已支持 list/get/deploy/enable/disable/export/import/remove/run，与其他命令共用 CAM 密钥，仅支持公有云站点。
+`adp workflow` 已支持 list/get/deploy/enable/disable/export/import/remove/run，与其他命令共用当前 profile 的密钥。公有云发到 `lke.tencentcloudapi.com`，独立站或自定义站点发到该 profile 的 ADP 主机。
 `workflow import` 遇到目标应用里有同名工作流会报 `WorkflowImportDuplicate`，缺变量报 `WorkflowImportMissingVariables`；启用后要发布应用才在生产生效。
 
 ## 应用包导入导出

package/skills/adp/references/app-modes.md

@@ -25,6 +25,7 @@ Integer enum on `CreateApp` / `adp.jsonc` `app_mode`:
 - `adp.jsonc` `agent.skill_ids` is meaningful for Claw (`4`). For mode `2`, leave it empty; the platform rejects skill mounts.
 - `agent.tools` is `{ plugin_id, tool_id }` (optional `tool_source`: 0 plugin / 1 workflow). `agent.plugin_ids` / `agent.plugins` enable plugins; `agent.connector_ids` are connectors (same `PluginList` on the wire). Do not stuff connector ids into `plugin_ids`.
 - Greeting, memory, web search, shared KBs, and Claw team prompt live on the **app**, not the agent: `greeting`, `memory`, `web_search`, `shared_kb_ids`, `mode.claw`.
+- **Claw sub-agents.** `app_mode` 4 has 1 main agent (`AgentProfile.Role=0`, stored as `adp.jsonc` `agent` / `agent_id`) and up to 19 sub-agents (`Role=1`). `CreateAgent` with `Role=0` is idempotent and returns the existing main agent (`AgentAlreadyExists` from the CLI). Add a sub-agent with `adp agent create --role 1` (`--description` is when the main agent should delegate). `ParentAgentId` is read-only on list/get. `mode.claw.team_enabled` and `mode.claw.team_prompt` turn on optional team collaboration; the default is one-way delegation from the main agent. Details: [../create/SKILL.md](../create/SKILL.md).
 - Default-KB documents: `adp kb doc import --file …` (KB id defaults to `app_id`). Create shared KBs with `adp kb create`; bind them with `shared_kb_ids`.
 - **`shared_kb_ids` is full-overwrite.** Omitting the key leaves bindings untouched;
   `[]` unbinds everything; a list replaces the whole set. Always read `adp app get`
@@ -32,5 +33,5 @@ Integer enum on `CreateApp` / `adp.jsonc` `app_mode`:
   prefix. Details: [pitfalls.md](pitfalls.md).
 - Sub-agents are not Tools. Never put a child `agent_id` into a plugin/tool list.
 - Binding an existing canvas workflow: `mode.single_workflow.workflow_id`. `adp workflow`
-  (CAM keys, cloud site only) can also list, get, deploy, enable, disable, export, import, remove, and async-run (`workflow run`, mode 3 with an entry workflow)
+  (same profile keys on the public cloud and the independent site) can also list, get, deploy, enable, disable, export, import, remove, and async-run (`workflow run`, mode 3 with an entry workflow)
   canvases; `adp app export` / `adp app import` move a released app as a package. The default export includes workflows, connectors, knowledge bases, agents, and skills (`--include` / `--exclude` / `--no-kb` narrow it; a selected workflow keeps the connectors and knowledge bases it references). A mode 3 copy whose package has no workflow files still needs its entry workflow exported, imported, and bound — see [../create/SKILL.md](../create/SKILL.md) §Workflows.

package/skills/adp/references/auth.md

@@ -53,8 +53,8 @@ adp auth status --format json
 
 ## 只有一套凭据
 
-所有命令（含 `adp workflow`、`adp kb doc`）都共用同一套 CAM SecretId/SecretKey（或独立站 API 密钥）。
-`adp workflow` 和 `adp kb doc import` 会调用 LKE 2023-11-30 接口，只支持公有云站点；
-鉴权失败时先看 `auth status` 的 `source`，再让用户确认 CAM 策略含 ADP 与 LKE 权限。
+所有命令（含 `adp workflow`、`adp kb doc`）都共用同一套 SecretId/SecretKey，公有云和独立站走同一套命令。
+`adp workflow` 和 `adp kb doc import` 里尚未迁到 ADP 的步骤调用 LKE 2023-11-30：公有云发到 `lke.tencentcloudapi.com`，独立站或自定义站点发到该 profile 的 ADP 主机。
+鉴权失败时先看 `auth status` 的 `source` 和站点。公有云再确认 CAM 策略含 ADP 与 LKE 权限；独立站确认密钥来自独立站密钥管理，而不是 CAM。
 不要反复登录，不要换应用绕过权限。
 `adp env list --format json` 只列环境变量名称和敏感标记，不返回值。

package/skills/adp/references/credentials.md

@@ -1,14 +1,50 @@
-# 凭证
+# 密钥与凭证
 
-凭证按空间可见（`--space-id` 或项目里的 `adp.jsonc`），供连接器/工具（插件）调用第三方服务时使用。
+本章节管理两类不同用途的凭据，切勿混用：
+
+1. **工具密钥（ADP API Key：`adp plugin key`）**：账号级 Bearer 密钥（对应控制台「工具密钥」），用于直接调用平台托管的 MCP 插件网关（`https://adp.cloud.tencent.com/plugin/mcp/<pluginId>/mcp`）。
+2. **连接器与插件出站凭证（`adp credential`）**：空间级凭证（`--space-id` 或 `adp.jsonc`），供插件/连接器在执行时访问第三方外部服务（如外部 API Key、OAuth 2.0）。
+
+> **相关索引**：如何使用工具密钥直接调用平台 MCP 插件（如可灵视频生成）、查看实时 MCP 工具列表，或将导出的 MCP 插件通过 CLI + Skill 无缝接入各个 Coding Agent，详见 [mcp.md](mcp.md)。
+
+---
 
 ## 安全规则
 
-- 秘密值只写不读：`list`/`get` 不返回 token；不要尝试从 CLI 输出里取回密钥。
-- API Key 只通过 `--token-env <变量名>` 或交互式隐藏输入传入。不要把密钥写进命令参数、文件、日志或回复里；没有现成环境变量时，让用户自己在终端里设置。
-- 只有创建者能 `get` 详情；别人的凭证报 `CredentialNotFound` 不代表不存在，不要据此删除或重建。
+- 秘密值默认不落日志、不进命令行参数：不要把明文密钥写进命令参数、代码仓库、配置文件（如 `mcp.json` / `SKILL.md`）、日志或对话回复。
+- 连接器凭证（`adp credential`）只写不读：`list`/`get` 不返回 token；创建或更新时仅通过 `--token-env <变量名>` 或交互式隐藏输入传入。
+- 工具密钥（`adp plugin key`）仅在 `create` 瞬间由云端返回一次明文，CLI 默认直接写入本机 `~/.adp/tool-key`（权限 `0600`），终端输出默认打码；`list` 接口只返回脱敏值（如 `lf***C9lG`），无法从服务端再次取回明文。
+
+---
 
-## 常用
+## 工具密钥（ADP API Key）
+
+用于鉴权直连平台 MCP 插件网关（调用方式见 [mcp.md](mcp.md#2-直接调用-mcp-插件如可灵)）。底层调用 LKE `CreateApiKey`、`DescribeApiKeyList`、`ModifyApiKey`、`ModifyApiKeyStatus`、`DeleteApiKey`。
+
+```bash
+adp plugin key list --format json                                      # 列出当前账号的工具密钥（脱敏值、status、lastAccessTime）
+adp plugin key create --description "kling" --format json              # 创建并默认写入 ~/.adp/tool-key (0600)，输出脱敏
+adp plugin key update --key-id <id> --description "new note" --format json
+adp plugin key disable --key-id <id> --format json                     # 禁用密钥（status 变为 2；删除前必须先禁用）
+adp plugin key enable --key-id <id> --format json                      # 重新启用密钥（status 变为 1）
+adp plugin key delete --key-id <id> --yes --format json                # 删除已禁用的密钥（若与 ~/.adp/tool-key 相同则同步清理本地文件）
+```
+
+- **明文保存与显示**：`adp plugin key create` 默认将明文保存到 `~/.adp/tool-key`（权限 `0600`），不在终端回显完整密钥。仅当用户明确需要在终端查看明文时才加 `--reveal`。若传 `--no-save` 则必须同时加 `--reveal`，否则 CLI 拒绝执行，防止密钥创建后丢失。
+- **密钥读取优先级**：当执行 `adp plugin tool call` 或 `adp plugin tool list`（见 [mcp.md](mcp.md)）时，按 `--api-key-env <变量名>` → 环境变量 `ADP_API_KEY` → `~/.adp/tool-key` 顺序读取。
+- **数量上限与清理流程（`4509400` / `ToolKeyLimitReached`）**：
+  - 平台每个账号最多允许同时存在 **2 把**工具密钥。超出时 `adp plugin key create`（以及真实执行的 `--auto-create-key`）报冲突错误 `ToolKeyLimitReached`（云端 `FailedOperation: 4509400-创建的密钥已达到上限`，退出码 `5`）。
+  - 由于已有密钥的明文无法从服务端取回，若本机没有 `~/.adp/tool-key` 且未设置 `ADP_API_KEY`：
+    1. 先运行 `adp plugin key list --format json` 查看现有密钥（`lastAccessTime` 为 `"0"` 表示从未使用过的闲置密钥）。
+    2. 向用户确认要清理哪一把后，**必须先禁用再删除**：先执行 `adp plugin key disable --key-id <id> --format json`，再执行 `adp plugin key delete --key-id <id> --yes --format json`。
+    3. 未禁用直接删除会报冲突错误 `ToolKeyNotDisabled`（云端 `4509404-密钥未处于禁用状态，请先禁用后再删除`，退出码 `5`）。
+    4. 删除腾出额度后，再执行 `adp plugin key create --format json`。若用户手头已有明文密钥，直接将其设置到环境变量 `ADP_API_KEY` 即可，无需删旧建新。
+
+---
+
+## 连接器与插件出站凭证（`adp credential`）
+
+按空间可见，供插件/连接器调用第三方外部服务时使用。只有创建者能 `get` 详情；别人的凭证报 `CredentialNotFound` 不代表不存在，不要据此删除或重建。
 
 ```bash
 adp credential list --space-id <id> --fields credentialId,name,typeLabel,consumer --format json
@@ -26,10 +62,12 @@ adp credential access --space-id <id> --credential-id <id> --referrer-type app_a
 - `delete` 前 CLI 会查引用，被引用时报 `CredentialInUse` 且不删除。先用 `references` 告诉用户哪些应用/工作台在用，由用户决定替换方案；删除需要用户明确同意才加 `--yes`。
 - `adp plugin oauth-url --plugin-id <id> --credential-id <id>` 为已有 OAuth 凭证生成授权链接，同样交给用户本人打开；`adp plugin auth check --plugin-id <id> --credential-id <id>` 查是否已授权（部分账号报 450002 无权限）。非 OAuth 2.0 插件报 `PluginNotOAuth`。
 
-## 插件工具与跨空间共享
+---
+
+## 插件工具详情与跨空间共享
 
 ```bash
-adp plugin tool get --plugin-id <id> --tool-id <id> --format json      # 工具入参/出参，tool-id 见 adp plugin get
+adp plugin tool get --plugin-id <id> --tool-id <id> --format json      # 工具入参/出参，tool-id 见 adp plugin get（直接调用 MCP 工具见 mcp.md）
 adp plugin share get --plugin-id <id> [--pending] --format json         # scope: none | all | spaces；--pending 没有待审批配置时返回 hasPending:false
 adp plugin share set --plugin-id <id> --scope spaces --space <sp> --yes --format json
 adp plugin share set --plugin-id <id> --credential <cid>=all --yes      # 只改某个凭证的共享范围

package/skills/adp/references/mcp.md

@@ -0,0 +1,78 @@
+# MCP 插件调用与接入
+
+平台上 `pluginKind = 2` 的插件（例如「可灵视频生成」）通过统一的 Streamable HTTP MCP 网关对外提供工具列表与直接调用能力。
+
+> **相关索引**：MCP 网关鉴权使用的是 **ADP API Key（工具密钥，`adp plugin key`）**，而非 CAM `SecretId`/`SecretKey` 或连接器出站凭证。工具密钥的创建、查看、启停、删除与 2 把配额上限处理，详见 [credentials.md](credentials.md#工具密钥adp-api-key)；插件调用第三方服务所需的出站凭证与 OAuth 授权，见 [credentials.md](credentials.md#连接器与插件出站凭证adp-credential)。
+
+---
+
+## 1. 平台 MCP 网关地址与协议
+
+- **固定地址格式**：`https://adp.cloud.tencent.com/plugin/mcp/<pluginId>/mcp`
+- **传输协议**：MCP JSON-RPC 2.0（Streamable HTTP），依次执行 `initialize`、`notifications/initialized`，再执行 `tools/list` 或 `tools/call`。
+- **鉴权方式**：请求头 `Authorization: Bearer <ADP API Key>`。CLI 仅向该网关白名单前缀发送 Bearer Token，且拒绝重定向。
+- **密钥读取顺序**：`--api-key-env <变量名>` → 环境变量 `ADP_API_KEY` → 本地文件 `~/.adp/tool-key`（由 `adp plugin key create` 默认以 `0600` 权限写入，见 [credentials.md](credentials.md#工具密钥adp-api-key)）。若显式传了 `--api-key-env` 但对应变量为空，CLI 会直接报错而不会回退到其他密钥。
+
+---
+
+## 2. 直接调用 MCP 插件（如可灵）
+
+1. **查找 MCP 插件 ID**：先用 `adp space list --format json` 获取空间 ID，再执行 `adp plugin list --space-id <id> --query "可灵" --format json`，确认目标插件的 `pluginKind` 为 `2`（例如可灵视频生成插件 ID 形如 `651c15de-2756-40f5-9c91-442a48767065`，以实际查询结果为准，不要凭记忆硬编码）。
+2. **查看工具与入参 Schema**：
+   - 从平台目录读取：`adp plugin get --space-id <id> --plugin-id <id> --format json` 查看 `tools[]` 的 `toolId` 与 `name`，再用 `adp plugin tool get --plugin-id <id> --tool-id <toolId> --format json` 查看单个工具的入参/出参定义。
+   - 从 MCP 网关实时读取：`adp plugin tool list --plugin-id <id> --format json` 直接向 MCP Server 发送 `tools/list`，返回所有实时工具的 `name`、`description` 与 `inputSchema`。
+3. **准备工具密钥**：若本机尚无 `~/.adp/tool-key` 且未设置 `ADP_API_KEY`，先运行 `adp plugin key create --format json` 生成并保存工具密钥（或在调用时加 `--auto-create-key`）。如遇密钥数量上限（`ToolKeyLimitReached` / `4509400`），按 [credentials.md](credentials.md#工具密钥adp-api-key) 先禁用并删除闲置密钥后再创建。
+4. **发起工具调用**：
+
+```bash
+# 按工具名直接调用（无需额外请求 Cloud API 反查名称）
+adp plugin tool call --plugin-id <id> --tool-name SubmitKlingTextToVideoJob --input '<json>' --format json
+
+# 按工具 ID 调用（CLI 自动通过 DescribeTool 反查工具名后再调 MCP）
+adp plugin tool call --plugin-id <id> --tool-id <toolId> --input '<json>' --dry-run --format json
+
+# 实时列出 MCP 服务端工具及 JSON Schema
+adp plugin tool list --plugin-id <id> --format json
+```
+
+### 调用参数与注意事项
+
+- `--tool-name` 与 `--tool-id` 二选一即可；同时传入但名称不一致时报 `UsageError`。
+- `--input`（别名 `--args`）接收 JSON 对象字符串，默认为 `{}`。
+- `--dry-run`：仅预览将要请求的 MCP URL、工具名与解析后的参数，不发送 HTTP 请求。即使本机尚未配置工具密钥且未传 `--auto-create-key`，`--dry-run` 仍会成功返回预览（`hasKey: false`），并提示在真实调用前执行 `adp plugin key create` 或加 `--auto-create-key`。
+- `--auto-create-key`：当本机没有可用工具密钥时，自动创建一把写入 `~/.adp/tool-key` 并完成调用，全程不在输出中打印明文；与 `--dry-run` 同用时仅标记 `wouldCreateKey: true`，不会真正创建密钥。
+- `--timeout-ms`：默认 `60000`（60 秒），提交视频生成等耗时任务时可适当调大（上限 `600000`）。
+- **异步任务两步走**：视频生成等长耗时工具通常拆分为 `Submit*`（如 `SubmitKlingTextToVideoJob`）与 `Query*`（如 `QueryKlingTextToVideoJob`）。先调 `Submit*` 从返回结果中取出任务 ID（如 `data.id`），再将其作为 `{"task_id": "<id>"}` 传给对应的 `Query*` 工具轮询状态。
+
+---
+
+## 3. 将导出的 MCP 插件无缝装入任意 Coding Agent（CLI + Skill 方式）
+
+无需在各个 Coding Agent 的 `mcp.json` 中硬编码明文 Bearer Token，通过 `adp` CLI + Skill 即可在 `claude`、`cursor`、`codex`、`agents`、`codebuddy`、`workbuddy` 中安全、无缝地调用任何 ADP MCP 插件：
+
+1. **方式一：安装通用 `adp` 伴生 Skill（推荐，一次安装即可按需调用全部 MCP 插件）**
+   - 预览安装目录：`adp skills install --dry-run --format json`（支持 `--scope global|project` 与 `--agent cursor,claude,codex,agents,codebuddy,workbuddy`）。
+   - 执行安装：`adp skills install --yes --format json`（WorkBuddy 连接器环境已内置，无需执行）。
+   - 确保本机已通过 `adp plugin key create --format json` 生成并缓存 `~/.adp/tool-key`（权限 `0600`，详见 [credentials.md](credentials.md#工具密钥adp-api-key)）。此后任何安装了该 Skill 的 Coding Agent 均可按本页第 2 节自动发现并调用目标插件。
+2. **方式二：为特定 MCP 插件派生独立专属 Skill（适合高频使用的单一插件，如“可灵”）**
+   - 先执行 `adp plugin get --space-id <id> --plugin-id <pluginId> --format json` 与 `adp plugin tool list --plugin-id <pluginId> --format json`，获取该插件全部工具的 `name`、`description` 和 `inputSchema`。
+   - 确认本机工具密钥已就绪（`adp plugin tool list` 返回 `hasKey: true`）。
+   - 在目标 Coding Agent 的 skills 目录（全局如 `~/.cursor/skills/<skill-name>/SKILL.md`、`~/.claude/skills/<skill-name>/SKILL.md`，或项目级 `.cursor/skills/`、`.claude/skills/` 等）创建专属 `SKILL.md`：
+     - Frontmatter 的 `description` 写明该插件的能力与触发词。
+     - 正文写明固定的 `--plugin-id <pluginId>`、各工具的 `name` 与入参 JSON Schema，以及标准调用模板：
+       `adp plugin tool call --plugin-id <pluginId> --tool-name <ToolName> --input '<json>' --format json`
+     - **严禁**将 `ADP_API_KEY` 明文写入 `SKILL.md` 或 `mcp.json`；调用时由 `adp plugin tool call` 自动从 `~/.adp/tool-key` 或环境变量读取（安全规则见 [credentials.md](credentials.md#安全规则)）。
+
+---
+
+## 4. 在空间目录中注册自定义外部 MCP Server
+
+若要将外部自建的 MCP Server 注册为 ADP 空间中的插件（供应用内 Agent 绑定使用）：
+
+```bash
+adp plugin create --space-id <id> --name <name> --mcp-url https://your-mcp-server.example/mcp --mcp-transport 1 --icon-url https://cdn.xiaowei.qq.com/static/adp/app-default-avatar.png --format json
+adp plugin update --space-id <id> --plugin-id <id> --mcp-url https://your-mcp-server.example/mcp --mcp-transport 1 --format json
+```
+
+- `--mcp-transport`：`0` 表示 SSE + HTTP，`1` 表示 Streamable HTTP。
+- 平台在创建和更新时会立即连接 `--mcp-url` 校验连通性，因此地址必须是真实可达的线上地址（占位域名会报 `460030`）。

package/skills/adp/references/pitfalls.md

@@ -3,6 +3,12 @@
 Symptom → cause → fix. Each one constrains an API this CLI already calls. Verify the
 platform side with `adp docs search "<action>" --format json` when in doubt.
 
+## Windows 启动与本地文件
+
+- Windows 连接器使用 `adp.cmd`。若连 `--version` 都抛 `ERR_UNSUPPORTED_ESM_URL_SCHEME`，是旧版入口加载故障，不是账号/网络失败；登录或重复连接无法修复。需更新实际安装副本到含修复的发布版，WorkBuddy 托管前缀可能不同于普通 npm 全局前缀。
+- 本地文件路径按宿主系统解析，中文/空格需作为一个参数传递，`..` 与 UNC/盘符使用原生语义；远端 COS/ZIP 路径仍按远端规则。不要把用户名或路径当作资源 ID。
+- POSIX 私密文件为0600；Windows依赖用户目录ACL，不要声称chmod提供仅本人访问，也不要把凭据写进共享目录或聊天。
+
 ## Single-workflow `WorkflowId` must be written through the bind path
 
 - **Symptom**: the workflow is deployed and enabled, but `adp app get` still shows an