@tencentcloudadp/cli 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloudadp/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI for Tencent Cloud Agent Development Platform (ADP)",
   "type": "module",
   "bin": {

package/skills/adp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adp
-description: 使用 @tencentcloudadp/cli 在终端或 CI 管理腾讯云 ADP 的空间、应用、智能体、草稿、发布、对话、知识库、渠道和工作流。用户明确提到 ADP、adp 命令或腾讯云智能体开发平台时使用；不用于一般 Agent 开发、其他厂商平台、CLI 源码开发或直接操作 workbench MCP。
+description: 使用 @tencentcloudadp/cli 在终端或 CI 管理腾讯云 ADP 的空间、应用、智能体、草稿、发布、对话、知识库、渠道和工作流。用户明确提到 ADP、adp 命令或腾讯云智能体开发平台时使用；不用于一般 Agent 开发、其他厂商平台或 CLI 源码开发。
 metadata:
   requires:
     bins: ["adp"]
@@ -8,7 +8,7 @@ metadata:
 
 # ADP CLI
 
-通过 `adp` 执行任务，不手写 Cloud API 签名，不直接调用 workbench MCP。
+通过 `adp` 执行任务，不手写 Cloud API 签名。
 缺少命令时安装 `npm install -g @tencentcloudadp/cli`。这个目录是 coding-agent
 配套 skill；`adp skill` 是平台的技能目录管理，`adp skills` 才是配套 skill 的发现入口。
 
@@ -16,11 +16,14 @@ metadata:
 
 会话里第一次执行写入或查询前，先运行 `adp auth status --format json`。退出码 `4` 表示本机没有凭据：
 
-1. 运行 `adp auth login --web --detach --format json`，把返回的 `result.url`（`127.0.0.1` 本地页面）交给用户，
-   说明在页面里填写 SecretId/SecretKey。公有云密钥在 CAM 控制台创建；独立站密钥在 https://adp.tencent.com/adp#/key-manage 获取。不要把密钥发到对话里。
-2. 每隔几秒重跑 `adp auth status --format json`，成功后继续原任务；到 `result.expiresAt` 仍未成功就停下说明。
+1. 默认在对话里向用户确认站点（公有云 `cloud` 或独立站 `independent`）以及对应的 `SecretId` / `SecretKey`。
+   **向用户提问时，必须在回复中分别列出两个站点的密钥创建 URL 引导**：
+   - **公有云（`cloud`）**：前往腾讯云 CAM API 密钥管理 https://console.cloud.tencent.com/cam/capi 创建或查看 `SecretId`（以 `AKID` 开头）与 `SecretKey`（主账号或子账号需具备 ADP 相关权限，详见 https://cloud.tencent.com/document/product/598/40488 ）。
+   - **独立站（`independent`）**：前往 ADP 独立站密钥管理 https://adp.tencent.com/adp#/key-manage （企业管理 → 密钥管理 → 新建 API 密钥）创建并获取 `SecretId` 与 `SecretKey`。
+   拿到用户回复后，执行 `adp auth login --site <cloud|independent> --secret-id "<id>" --secret-key "<key>" --format json`，再用 `adp auth status --format json` 确认生效。
+2. 仅当用户明确要求通过网页/浏览器填写密钥时，运行 `adp auth login --web --detach --format json`，把返回的 `result.url`（`127.0.0.1` 本地页面）交给用户，并轮询 `adp auth status --format json` 直到成功或到 `result.expiresAt` 超时。
 
-不在对话中索取密钥，不使用 `--secret-id/--secret-key` 参数。细节见 [references/auth.md](references/auth.md)。
+不要在回复、日志或报告中回显完整 SecretKey。已有凭据但接口返回权限不足（`4` 且 `source` 存在）时，先检查 `auth status` 的 `source` 并提示补齐权限，不要盲目重登。细节见 [references/auth.md](references/auth.md)。
 
 ## 先定位，再展开
 
@@ -108,7 +111,7 @@ adp schema --command "channel" --compact --format json
   退出 0，envelope 的 `warnings[]`（`UnknownField`）列出未知与可用字段；文本模式写 stderr。
   空列表没有字段可校验，正常返回空数组。字段仅在后续行出现时也可选取。
 - 退出码：`0` 成功、`1` 内部/上游、`2` 参数、`3` 不存在、`4` 鉴权、`5` 冲突、`6` 限流。
-  参数错误先读取提示中的局部 schema。鉴权失败检查来源，不在聊天中索取或输出密钥。
+  参数错误先读取提示中的局部 schema。已有凭据但鉴权失败时先检查来源和 CAM/站点权限，不在回复中回显完整密钥。
   仅在 `retryable=true` 且操作可以安全重试时有限退避；非幂等写入先确认远端是否已生效。
 - `--verbose` 仅在普通 hint 无法解释失败时使用；输出可能包含敏感上游数据，分享前检查。
 

package/skills/adp/create/SKILL.md

@@ -32,7 +32,7 @@ adp models --format json --fields modelId,name --limit 20
 adp models --scene 18 --space-id "<space_id>" --format json --fields modelId,name   # Claw (app_mode 4)
 ```
 
-需要 `space_id` 和 `model_id`。Claw 应用只能用 `--scene 18` 列出的模型，否则发布报 `4600005-应用配置不完整`；不传 `--model-id` 时 `init --create-remote` 自动取该列表第一项，目前通常是 `Auto/auto`（平台自动选模型，可以正常发布）；要固定模型就显式传 `--model-id`。不带 `--create-remote` 时写入占位值 `placeholder-model`，`adp deploy` 会拒绝，需先改成 scene 18 列表里的模型。非 Claw 模式不传 `--model-id` 时（含 `--create-remote`）同样写占位值，`init` 结果带 warning：多 Agent 要先换成 `adp models` 里的真实模型；1/3 模式没有智能体，不会发送这个值。`--model-id` 只写入 `agent.model.model_id`，通过 `ModifyAgent` 生效：标准模式（`1`）和单工作流（`3`）没有智能体，传了也不会改应用的生成模型（控制台仍显示 Auto），`init` 结果里会带 `warnings` 提示；这两种模式的模型请在控制台选择。`init --dry-run` 的 next_action 是去掉 `--dry-run` 的同一条 `adp init`（带 `--create-remote` 时附 `--yes`，会真的建应用）。不要把 SecretId/SecretKey 放到命令行或聊天中；agent 不等待交互登录。
+需要 `space_id` 和 `model_id`。Claw 应用只能用 `--scene 18` 列出的模型，否则发布报 `4600005-应用配置不完整`；不传 `--model-id` 时 `init --create-remote` 自动取该列表第一项，目前通常是 `Auto/auto`（平台自动选模型，可以正常发布）；要固定模型就显式传 `--model-id`。不带 `--create-remote` 时写入占位值 `placeholder-model`，`adp deploy` 会拒绝，需先改成 scene 18 列表里的模型。非 Claw 模式不传 `--model-id` 时（含 `--create-remote`）同样写占位值，`init` 结果带 warning：多 Agent 要先换成 `adp models` 里的真实模型；1/3 模式没有智能体，不会发送这个值。`--model-id` 只写入 `agent.model.model_id`，通过 `ModifyAgent` 生效：标准模式（`1`）和单工作流（`3`）没有智能体，传了也不会改应用的生成模型（控制台仍显示 Auto），`init` 结果里会带 `warnings` 提示；这两种模式的模型请在控制台选择。`init --dry-run` 的 next_action 是去掉 `--dry-run` 的同一条 `adp init`（带 `--create-remote` 时附 `--yes`，会真的建应用）。不要在回复中回显明文 SecretKey；agent 不等待 TTY 交互输入。
 
 ## Create (one shot)
 
@@ -129,11 +129,15 @@ adp workflow enable --app-id "<app_id>" --workflow-id "<wf_id>" --format json
 adp workflow export --app-id "<app_id>" --workflow-id "<wf_id>" --output ./wf.zip --format json
 # Same-name workflow in the target app → WorkflowImportDuplicate
 adp workflow import --app-id "<app_id>" --file ./wf.zip --enable --format json
-# Whole app (released apps only; run adp deploy first)
+# Whole app (released apps only; run adp deploy first). Default scope is app settings plus
+# every workflow, connector, knowledge base, agent, and skill. --include workflow,kb narrows it.
+# A pipe, CI, agent, or --yes does not prompt. A selected workflow keeps referenced connectors and knowledge bases.
 adp app export --app-id "<app_id>" --output ./app.zip --format json
 # Import that ZIP as a new unreleased app (copy; name gets 的副本NN)
 adp app import --space-id "<space_id>" --file ./app.zip --format json
-# The package holds app config only, never workflows. A mode 3 copy is NOT runnable until you
+# A full package already contains workflows (app/workflow/workflow_<id>.json inside app.zip)
+# and knowledge bases (knowledge_bases.zip and metadata.json Components.KnowledgeBases).
+# A settings-only package does not. A mode 3 copy of a settings-only package is NOT runnable until you
 # copy the entry workflow (500304 otherwise); import prints a warning plus these next_actions,
 # with the source app ID (from the package) and entry workflow ID (from the source draft) filled
 # in when the CLI can read them; otherwise it adds app list / app get lookups first:

package/skills/adp/gotchas/SKILL.md

@@ -80,13 +80,13 @@ Pagination: `--page` (0-based) works on page-numbered lists. Cursor lists do not
 
 ## 应用包导入导出
 
-- `adp app export` 只能导出**已发布**的应用（未发布报 `AppNotReleased`，先 `adp deploy`）；导出的是最新发布版本，`--release-id` 可指定版本。
+- `adp app export` 只能导出**已发布**的应用（未发布报 `AppNotReleased`，先 `adp deploy`）；导出的是最新发布版本，`--release-id` 可指定版本。默认包含该版本的应用设置，以及摘要里的全部工作流、连接器与工具、知识库、智能体、技能。人类终端没指定范围时会询问；管道、CI、检测到的 agent，或 `--yes`，不再询问并导出全部。`--include workflow,kb`（也接受 `connector` / `knowledge` / `config`，`config` 表示只要应用设置）、`--exclude skill`、`--no-kb` / `--no-workflow` / `--no-agent` / `--no-plugin` / `--no-skill`、`--component-id` 用来收窄范围。已选工作流引用的连接器和知识库会强制带上，不能用 `--no-kb` / `--no-plugin` 去掉。
 - `adp workflow run` 只适用于绑定了入口工作流的单工作流模式应用（`app_mode: 3`；实测 `async_workflow` 为 false 也能跑），其他模式报 `WorkflowRunUnsupported`（平台 500331）。工作流跑失败时命令仍成功返回，要看 `state`。运行停在需要用户回答的节点（选项卡 OPTION_CARD、参数提取追问等）时状态为 5（`stateLabel: "waiting_input"`，公开文档未列出），`run start` 立即返回 `status: "waiting_input"` 而不是等到超时，结果里的 `question` 是节点的追问（例如「请提供要查询的日期」）；把用户的回答接在 `adp workflow run resume --run-id … --query` 后面继续，resume 默认会等到下一个终态或等待态（`--no-wait` 立即返回），追问没答全会再次返回 `waiting_input` 和新的 `question`；已结束的运行不能 resume。参数提取的 `IncorrectExamples` 执行得很严：用户的写法和错误示例一样（实测「10月20日」）时节点会再追问，即使用户已经给了日期。意图识别节点把最后一个意图当兜底（输出 `IntentName: "Other"`，不交给模型判断），所以最后一个意图必须是显式的「其他」。对话里的选项卡同理：平台不展示最后一个选项（兜底分支），所以选项卡的最后一项也要是「其他」。`adp chat`（`adp deploy` 之后，对话打到已发布版本）把展示的选项放进 `result.optionCards`，并在 `reply` 末尾附上编号列表。排查 token 消耗用 `workflow run node --stats`。
 - `adp.jsonc` 的 `memory` 只是应用自带长期记忆的开关；独立的记忆库、条目和绑定用 `adp memory`（见 references/memory.md）。
 - `adp app template` 的所有子命令都需要空间（`--space-id` 或 `adp.jsonc`），模板库按空间可见。`use` 新建的应用默认与模板同名，用 `--name` 改名。
 - `adp app package retry` 只对失败的任务有效；`canRetry` 为 true 不代表能重试（报 `AppPackageTaskNotFailed`）。
-- `adp app import --space-id … --file …` 总是新建一个应用，状态为未上线，不会覆盖已有应用。发布副本用 `adp deploy --app-id <副本 appId> --yes`：带 `--app-id` 时只把该应用的远端草稿原样发布，不读 adp.jsonc、不推本地文件；import 的最后一条 next_action 就是这条命令。新应用的名称不保证带「的副本NN」：实测副本可能与源应用同名，按 `appId` 区分，不要按名称找。空间应用数已满时平台报 4900001（CLI 报 `AppQuotaExceeded`，`retryable: true`，next_action 是原命令）；`--no-wait` 的 next_action 是 `app list --space-id …`，新应用先以 status 4（导入中）出现。应用包只含应用配置，不含工作流和知识库文档/问答：标准/多 Agent 等模式的副本会收到 warning；能列出源应用工作流时，next_actions 对每个工作流给出具体的 `workflow export --app-id 源 --workflow-id … --output ./<名称>-<id>.zip` 和 `workflow import --app-id 新 --file 同一个 zip --enable`，列不出时给出源应用的 `workflow list`；最后是源应用的 `kb doc list`，文档要用 `kb doc import --kb-id 新应用 --file 原文件` 逐个重新导入。导入并启用的工作流随下一次 `adp deploy` 一起发布。单工作流（app_mode 3）副本的入口工作流不存在，运行报 500304。import 会给出 warning 和 next_actions：从源应用 `workflow export`，`workflow import --enable` 到副本，`workflow list` 查到新 id，再用 `workflow export` 结果里 `canvasFiles` 指向的 `<id>_workflow.json`（导出时已从 ZIP 解到同目录）执行 `workflow deploy --workflow-id 新id --canvas-file … --bind`。源应用 id 取自包里的 `base_config.json`，入口工作流 id 取自源应用草稿（导出包会把它置空）；读不到的 id 前面会多一步 `app list` / `app get`。
+- `adp app import --space-id … --file …` 总是新建一个应用，状态为未上线，不会覆盖已有应用。发布副本用 `adp deploy --app-id <副本 appId> --yes`：带 `--app-id` 时只把该应用的远端草稿原样发布，不读 adp.jsonc、不推本地文件；import 的最后一条 next_action 就是这条命令。新应用的名称不保证带「的副本NN」：实测副本可能与源应用同名，按 `appId` 区分，不要按名称找。空间应用数已满时平台报 4900001（CLI 报 `AppQuotaExceeded`，`retryable: true`，next_action 是原命令）；`--no-wait` 的 next_action 是 `app list --space-id …`，新应用先以 status 4（导入中）出现。完整导出的包包含工作流（`app.zip` 里的 `app/workflow/workflow_<id>.json` 和 `workflow_config.json`）和知识库（外层 `knowledge_bases.zip`，以及 `metadata.json` 的 `Components.KnowledgeBases`）；这种包导入后不再提示逐个复制。只有应用设置的包（或读不到这些文件时）会 warning：能列出源应用工作流时，next_actions 对每个工作流给出具体的 `workflow export --app-id 源 --workflow-id … --output ./<名称>-<id>.zip` 和 `workflow import --app-id 新 --file 同一个 zip --enable`，列不出时给出源应用的 `workflow list`；没有知识库时最后是源应用的 `kb doc list`，文档要用 `kb doc import --kb-id 新应用 --file 原文件` 逐个重新导入。导入并启用的工作流随下一次 `adp deploy` 一起发布。单工作流（app_mode 3）若包内没有工作流，入口工作流不存在，运行报 500304。import 会给出 warning 和 next_actions：从源应用 `workflow export`，`workflow import --enable` 到副本，`workflow list` 查到新 id，再用 `workflow export` 结果里 `canvasFiles` 指向的 `<id>_workflow.json`（导出时已从 ZIP 解到同目录）执行 `workflow deploy --workflow-id 新id --canvas-file … --bind`。源应用 id 取自包里的 `base_config.json`，入口工作流 id 取自源应用草稿（只导出应用设置时会把入口 WorkflowId 置空）；读不到的 id 前面会多一步 `app list` / `app get`。包内已有工作流时，mode 3 改为列出导入后的工作流，若运行仍报 500304 再 bind 入口。
 - `workflow import --enable` 导入的工作流不需要再 `workflow deploy`：下一次 `adp deploy` 发布应用时会一并发布它们（实测）。`adp deploy` 发布后仍会检查已启用但仍是 `UNPUBLISHED` 的工作流，这种情况很少见；出现时给出 warning（`unpublishedWorkflows`）和 next_action：先 `workflow export --output` 拿到 `<id>_workflow.json`，再 `workflow deploy --workflow-id … --yes`，然后重新 `adp deploy`。
 - 两个 export 命令不带 `--output` 时返回约 30 分钟有效的 `downloadUrl`，视同凭证，不要写进日志或回复里。
 读取 [../create/SKILL.md](../create/SKILL.md) 的 Workflows 部分和目标命令的 schema。
-画布编写、节点编辑不属于 CLI 的能力，不直接调用 workbench MCP 来绕过 CLI。
+工作流画布通过本地 JSON 与 `adp workflow deploy` 管理。

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

@@ -33,4 +33,4 @@ Integer enum on `CreateApp` / `adp.jsonc` `app_mode`:
 - 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)
-  canvases; `adp app export` / `adp app import` move a released app's config as a package (no workflows: a mode 3 copy needs its entry workflow exported, imported and bound again) — see [../create/SKILL.md](../create/SKILL.md) §Workflows.
+  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

@@ -11,7 +11,25 @@
 
 已有 profile 时无需重新登录。
 
-## 在对话里完成首次登录（WorkBuddy 等 agent 环境）
+## 在对话里完成首次登录（默认：Agent 交互填充）
+
+`adp auth status --format json` 返回退出码 `4`（无本机凭据）时，除非用户主动要求网页登录，默认直接与用户交互收集站点与 AK/SK 并写入 profile：
+
+1. 向用户确认站点（默认公有云 `cloud`；独立站为 `independent`；私有化/自定义传 `--site custom --endpoint <host>`）以及 `SecretId`、`SecretKey`（临时密钥可附加 `--token`）。**提问时必须在回复中同时给出两个站点的密钥获取 URL 与入口说明**：
+   - **公有云（`cloud`）**：在腾讯云 CAM 控制台 [API 密钥管理](https://console.cloud.tencent.com/cam/capi)（`https://console.cloud.tencent.com/cam/capi`）新建或获取 `SecretId`（`AKID` 开头）与 `SecretKey`（使用说明见 `https://cloud.tencent.com/document/product/598/40488`）。
+   - **独立站（`independent`）**：在 ADP 独立站 [密钥管理](https://adp.tencent.com/adp#/key-manage)（`https://adp.tencent.com/adp#/key-manage`，路径：企业管理 → 密钥管理 → 新建 API 密钥）创建并获取 `SecretId` 与 `SecretKey`。
+2. 收到用户提供的信息后，执行非交互登录写入本地 `~/.adp/profiles/`：
+
+```bash
+adp auth login --site <cloud|independent> --secret-id "<SecretId>" --secret-key "<SecretKey>" --format json
+adp auth status --format json
+```
+
+- 不要在回复、总结或报告中回显用户的明文 `SecretKey`，也不要将密钥写入仓库文件。
+
+## 从网页发起登录（仅当用户明确要求网页登录时）
+
+当用户明确要求通过网页/本地浏览器填写密钥，或拒绝在对话中粘贴密钥时，使用本地网页登录：
 
 ```bash
 adp auth login --web --detach --format json   # 返回 result.url / expiresAt / pid
@@ -20,25 +38,22 @@ adp auth status --format json                 # 轮询，直到 ok:true
 
 - 页面只监听 `127.0.0.1`，链接带一次性 token，默认 5 分钟过期（`--timeout <秒>` 调整，最长 1800）。
 - 页面先用一次只读调用校验密钥，校验失败会在页面上提示并允许重填，不会保存无效密钥。
-- 用户关闭页面或过期后重新执行一次 `--web --detach`；不要改为在对话中收集密钥。
 - `--site independent` / `--profile <name>` 可与 `--web` 同用；`--open` 会尝试直接打开浏览器。
 
-## 在终端或 CI 登录
+## 在终端或 CI 通过环境变量登录
 
-需要登录时让用户通过受保护的本地环境设置
-`TENCENTCLOUD_SECRET_ID`、`TENCENTCLOUD_SECRET_KEY`，然后运行：
+用户已在本地终端环境设置了 `TENCENTCLOUD_SECRET_ID`、`TENCENTCLOUD_SECRET_KEY` 时，可直接持久化当前环境凭据：
 
 ```bash
 adp auth login --site cloud --format json
 adp auth status --format json
 ```
 
-不要把密钥放进 CLI 参数、聊天、报告或仓库。CLI 为兼容保留了 secret 参数，agent 不使用。
-agent/非 TTY 缺凭据时退出，不等待交互输入；提示用户在本地完成安全配置。
+不要把密钥写进报告或仓库。非 TTY 且未传参数/环境变量时命令会直接退出，不会挂起等待终端输入。
 
 ## 只有一套凭据
 
-所有命令（含 `adp workflow`、`adp kb doc`）都只用 CAM SecretId/SecretKey，没有 Tool Key。
+所有命令（含 `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 权限。
 不要反复登录，不要换应用绕过权限。