@tencentcloudadp/cli 0.0.0-stage → 0.1.1

package/skills/adp/references/canvas/option.json

@@ -0,0 +1,97 @@
+{
+ "ProtoVersion": "V2_6",
+ "WorkflowID": "",
+ "WorkflowName": "zz-demo-option",
+ "WorkflowDesc": "Ask the user to pick a plan with an option card, then branch on the choice",
+ "Nodes": [
+  {
+   "NodeID": "start",
+   "NodeName": "Start",
+   "NodeDesc": "",
+   "NodeType": "START",
+   "StartNodeData": {},
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": [
+    "opt"
+   ]
+  },
+  {
+   "NodeID": "opt",
+   "NodeName": "选择套餐",
+   "NodeDesc": "",
+   "NodeType": "OPTION_CARD",
+   "OptionCardNodeData": {
+    "Question": "请选择套餐：",
+    "Options": [
+     {
+      "Content": "基础版",
+      "NextNodeIDs": [
+       "ans_basic"
+      ]
+     },
+     {
+      "Content": "专业版",
+      "NextNodeIDs": [
+       "ans_pro"
+      ]
+     }
+    ],
+    "CardFrom": "INPUT"
+   },
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": []
+  },
+  {
+   "NodeID": "ans_basic",
+   "NodeName": "ans_basic",
+   "NodeDesc": "",
+   "NodeType": "ANSWER",
+   "AnswerNodeData": {
+    "Answer": "PLAN=BASIC"
+   },
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": [
+    "end"
+   ]
+  },
+  {
+   "NodeID": "ans_pro",
+   "NodeName": "ans_pro",
+   "NodeDesc": "",
+   "NodeType": "ANSWER",
+   "AnswerNodeData": {
+    "Answer": "PLAN=PRO"
+   },
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": [
+    "end"
+   ]
+  },
+  {
+   "NodeID": "end",
+   "NodeName": "End",
+   "NodeDesc": "",
+   "NodeType": "END",
+   "Inputs": [],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [],
+     "Desc": "Output content",
+     "Value": {
+      "InputType": "USER_INPUT"
+     },
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": []
+  }
+ ],
+ "Mode": "NORMAL"
+}

package/skills/adp/references/canvas/single.json

@@ -0,0 +1,155 @@
+{
+ "ProtoVersion": "V2_6",
+ "WorkflowID": "",
+ "WorkflowName": "zz-demo-single",
+ "WorkflowDesc": "Echo the user query as WF-OK:{query}",
+ "Nodes": [
+  {
+   "NodeID": "start",
+   "NodeName": "Start",
+   "NodeDesc": "",
+   "NodeType": "START",
+   "StartNodeData": {},
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": [
+    "code1"
+   ]
+  },
+  {
+   "NodeID": "code1",
+   "NodeName": "拼接",
+   "NodeDesc": "",
+   "NodeType": "CODE_EXECUTOR",
+   "CodeExecutorNodeData": {
+    "Code": "def main(params: dict) -> dict:\n    return {\"result\": \"WF-OK:\" + str(params.get(\"q\", \"\"))}\n",
+    "Language": "PYTHON3"
+   },
+   "Inputs": [
+    {
+     "Name": "q",
+     "Type": "STRING",
+     "Input": {
+      "InputType": "SYSTEM_VARIABLE",
+      "SystemVariable": {
+       "Name": "SYS.UserQuery"
+      }
+     },
+     "Desc": "",
+     "IsRequired": false,
+     "SubInputs": [],
+     "DefaultValue": "",
+     "DefaultFileName": ""
+    }
+   ],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [
+      {
+       "Title": "result",
+       "Type": "STRING"
+      }
+     ],
+     "Desc": "",
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": [
+    "answer1"
+   ],
+   "ExceptionHandling": {
+    "Switch": "OFF",
+    "MaxRetries": "3",
+    "RetryInterval": "1",
+    "AbnormalOutputResult": "",
+    "HandleMethod": "EXCEPTION_OUTPUT",
+    "NextNodeIDs": [],
+    "AbnormalRetrySwitch": "ABNORMAL_RETRY_ON",
+    "Timeout": "60"
+   }
+  },
+  {
+   "NodeID": "answer1",
+   "NodeName": "回答",
+   "NodeDesc": "",
+   "NodeType": "ANSWER",
+   "AnswerNodeData": {
+    "Answer": "{{content}}"
+   },
+   "Inputs": [
+    {
+     "Name": "content",
+     "Type": "STRING",
+     "Input": {
+      "InputType": "REFERENCE_OUTPUT",
+      "Reference": {
+       "NodeID": "code1",
+       "JsonPath": "Output.result"
+      }
+     },
+     "Desc": "",
+     "IsRequired": false,
+     "SubInputs": [],
+     "DefaultValue": "",
+     "DefaultFileName": ""
+    }
+   ],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [
+      {
+       "Title": "Answer",
+       "Type": "STRING",
+       "Required": [],
+       "Properties": [],
+       "Desc": "Reply to User Message",
+       "Value": {
+        "InputType": "USER_INPUT",
+        "UserInputValue": {
+         "Values": [
+          ""
+         ],
+         "FileNames": []
+        }
+       },
+       "AnalysisMethod": "COVER"
+      }
+     ],
+     "Desc": "Output content",
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": [
+    "end"
+   ]
+  },
+  {
+   "NodeID": "end",
+   "NodeName": "End",
+   "NodeDesc": "",
+   "NodeType": "END",
+   "Inputs": [],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [],
+     "Desc": "Output content",
+     "Value": {
+      "InputType": "USER_INPUT"
+     },
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": []
+  }
+ ],
+ "Mode": "NORMAL"
+}

package/skills/adp/references/canvas/sub.json

@@ -0,0 +1,125 @@
+{
+ "ProtoVersion": "V2_6",
+ "WorkflowID": "",
+ "WorkflowName": "research-step",
+ "WorkflowDesc": "Sub-workflow: takes topic, returns SUB:{topic}",
+ "Nodes": [
+  {
+   "NodeID": "start",
+   "NodeName": "Start",
+   "NodeDesc": "",
+   "NodeType": "START",
+   "StartNodeData": {},
+   "Inputs": [
+    {
+     "Name": "topic",
+     "Type": "STRING",
+     "Desc": "topic",
+     "IsRequired": true,
+     "SubInputs": [],
+     "DefaultValue": "",
+     "DefaultFileName": ""
+    }
+   ],
+   "Outputs": [],
+   "NextNodeIDs": [
+    "code1"
+   ]
+  },
+  {
+   "NodeID": "code1",
+   "NodeName": "子处理",
+   "NodeDesc": "",
+   "NodeType": "CODE_EXECUTOR",
+   "CodeExecutorNodeData": {
+    "Code": "def main(params: dict) -> dict:\n    return {\"result\": \"SUB:\" + str(params.get(\"topic\", \"\"))}\n",
+    "Language": "PYTHON3"
+   },
+   "Inputs": [
+    {
+     "Name": "topic",
+     "Type": "STRING",
+     "Input": {
+      "InputType": "REFERENCE_OUTPUT",
+      "Reference": {
+       "NodeID": "start",
+       "JsonPath": "topic"
+      }
+     },
+     "Desc": "",
+     "IsRequired": false,
+     "SubInputs": [],
+     "DefaultValue": "",
+     "DefaultFileName": ""
+    }
+   ],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [
+      {
+       "Title": "result",
+       "Type": "STRING"
+      }
+     ],
+     "Desc": "",
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": [
+    "end"
+   ],
+   "ExceptionHandling": {
+    "Switch": "OFF",
+    "MaxRetries": "3",
+    "RetryInterval": "1",
+    "AbnormalOutputResult": "",
+    "HandleMethod": "EXCEPTION_OUTPUT",
+    "NextNodeIDs": [],
+    "AbnormalRetrySwitch": "ABNORMAL_RETRY_ON",
+    "Timeout": "60"
+   }
+  },
+  {
+   "NodeID": "end",
+   "NodeName": "End",
+   "NodeDesc": "",
+   "NodeType": "END",
+   "Inputs": [],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [
+      {
+       "Title": "result",
+       "Name": "result",
+       "Type": "STRING",
+       "Required": [],
+       "Properties": [],
+       "Desc": "",
+       "AnalysisMethod": "COVER",
+       "Value": {
+        "InputType": "REFERENCE_OUTPUT",
+        "Reference": {
+         "NodeID": "code1",
+         "JsonPath": "Output.result"
+        }
+       }
+      }
+     ],
+     "Desc": "Output content",
+     "Value": {
+      "InputType": "USER_INPUT"
+     },
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": []
+  }
+ ],
+ "Mode": "NORMAL"
+}

package/skills/adp/references/credentials.md

@@ -0,0 +1,40 @@
+# 凭证
+
+凭证按空间可见（`--space-id` 或项目里的 `adp.jsonc`），供连接器/工具（插件）调用第三方服务时使用。
+
+## 安全规则
+
+- 秘密值只写不读：`list`/`get` 不返回 token；不要尝试从 CLI 输出里取回密钥。
+- API Key 只通过 `--token-env <变量名>` 或交互式隐藏输入传入。不要把密钥写进命令参数、文件、日志或回复里；没有现成环境变量时，让用户自己在终端里设置。
+- 只有创建者能 `get` 详情；别人的凭证报 `CredentialNotFound` 不代表不存在，不要据此删除或重建。
+
+## 常用
+
+```bash
+adp credential list --space-id <id> --fields credentialId,name,typeLabel,consumer --format json
+adp credential consumers --space-id <id> --format json                      # 已配凭证的连接器/工具
+adp credential referable --space-id <id> --consumer-id <plugin_id> --format json
+adp credential create --space-id <id> --consumer-id <plugin_id> --name <name> --token-env MY_KEY --format json
+adp credential update --space-id <id> --credential-id <id> --token-env NEW_KEY --format json
+adp credential references --space-id <id> --credential-id <id> --format json
+adp credential access --space-id <id> --credential-id <id> --referrer-type app_agent --referrer-id <agent_id> --format json  # 该引用方能否用此凭证
+```
+
+- `typeLabel`：`api_key`、`cam`、`oauth`、`aksk`。CLI 只能新建 API Key 凭证；腾讯云 CAM 凭证请用户在控制台创建。
+- OAuth：`adp credential authorize --consumer-id <plugin_id>`（新建）或 `--credential-id <id>`（重新授权）返回 `authorizationUrl`，必须由用户本人在浏览器打开并同意；之后用 `adp credential authorization --authorization-id <auth_…>` 查结果（1 授权中、2 成功、4 失败）。平台对过期和不存在的授权号都回 3，CLI 统一报 `CredentialAuthorizationNotFound`（退出码 3），这时让用户重新 `adp credential authorize`。不要替用户打开或提交授权页。
+- `credential access` 返回 `accessible` 和 `inaccessibleReason`，用于排查「智能体/工作流调用插件报凭证不可用」。引用方没引用该凭证时报 `CredentialNotReferenced`。
+- `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 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      # 只改某个凭证的共享范围
+```
+
+- 共享是对外可见的变更，先问用户；可能进入审批（`status: "pending_approval"`），不要替用户催审或绕过。
+- `PluginShareBlocked`：还有应用/智能体在用被收回的范围。把引用方列给用户，由用户决定先解绑；`--force --confirm-name <插件名>` 只给空间管理员用，且必须用户明确要求。
+- `PluginShareRevisionConflict`：别人刚改过，直接重跑即可。

package/skills/adp/references/inventory.md

@@ -0,0 +1,39 @@
+# 应用盘点
+
+默认范围来自 `adp.jsonc` 的 `space_id`，也可显式 `--space-id`。
+只有用户要求跨空间盘点时才用 `--all-spaces`；无配置不等于授权扫描所有空间。
+
+没有 `adp.jsonc` 时，先列一个空间，再列该空间的应用，然后对单个应用列会话。失败信封里的 `adp init` 会写项目文件，不要执行。
+
+```bash
+adp schema --command "app list" --format json
+adp space list --format json
+adp app list --space-id <id> --fields appId,name,status,updateTime,spaceId --limit 50 --format json
+adp conversation list --app-id <appId> --format json
+```
+
+读取 `truncated/total`；截断时提高 `--limit`，保留原来的空间、profile、env 和 fields。
+未知 total 时逐步提高 limit 并设置调用次数上限；仍截断就明确报告不完整，不无限重试。
+CLI 内部跟随 API 的 PageNumber/PageSize，不手签 Cloud API 分页。
+`--page` 对每个列表命令都是 0 起始（首页是 `--page 0`），CLI 会换算成各 API 自己的起始页；
+带 `--page` 时结果含 `page/pageSize`，截断时用 `--page <n+1>` 续取。
+空列表表示当前范围无可见结果，不是权限完整性证明。
+
+应用 `status`：1 未发布、2 运行中、3 已停用。`status` 与 `updateTime` 只能作为活跃代理指标。
+`conversation list` 返回的会话属于当前凭据可见范围。结果字段 `scope` 的值是 `owner`，没有 `--scope` 参数。这不是应用所有 C 端请求量。
+先 list，再用返回的 `conversationId` 和该行的 `type` 读消息：
+
+```bash
+adp conversation messages --conversation-id <id> --type <type-from-list> --format json
+```
+
+`messages` 同样是当前 CAM 可见范围。结果没有 `total`，也不走 `PageNumber`。`truncated=true` 且 `hasMoreBefore=true` 时，用返回的 `firstRecordId` 向更早翻页，并保留原来的 `--type`：
+
+```bash
+adp conversation messages --conversation-id <id> --type <type-from-list> --record-id <firstRecordId> --direction backward --format json
+```
+
+`truncated=true` 且 `hasMoreAfter=true`、方向是 forward 或 both 时，用 `lastRecordId` 和 `--direction forward`，同样保留 `--type`。
+
+字段到正文、引用、角标、任务状态、MCP `toolResult`、token 摘要，以及消息上的 `type`（含 `tool_call`）、`trace.toolName` 和 `trace.traceId`。工具调用的入参在 `title`，结果在对应 content 的 `text`。`reasoningTokens` 只是计数，没有单独的思考正文。消息接口不接受 `--type 0`，把 list 行上的 `type` 传进去；省略时默认 1。
+`adp usage` 返回该应用近 7 天的模型用量 KPI（`total_calls`、`total_tokens` 等），需要 `--app-id` 或 `adp.jsonc`。返回 450002 时是权限失败；不要把失败、空值或 owner 会话数当真实调用量。

package/skills/adp/references/memory.md

@@ -0,0 +1,54 @@
+# 记忆库
+
+记忆库按空间可见：传 `--space-id`，或在有 `adp.jsonc` 的项目里运行。
+它和 `adp.jsonc` 的 `memory`（应用自带的长期记忆开关）是两回事；用户说“记忆库”“记忆条目”“绑定记忆库”时用 `adp memory`。
+
+ID 前缀决定类型，CLI 自动推断，不用传类型：
+
+- `rms_…` 结构化记忆库（rich）：条目有名称、类型、front matter、版本，每个终端用户可有一份 L2 摘要。
+- `fms_…` 扁平记忆库（flat）：只有类型和正文，可设保留天数（`ttl_days`，0 为永久）。类型创建后不能改。
+
+## 查看
+
+```bash
+adp memory list --space-id <id> --fields storeId,name,typeName,referencedApps --format json
+adp memory users --space-id <id> --store-id <store> --format json
+adp memory entry list --space-id <id> --store-id <store> --user-id <user> --format json
+adp memory summary get --space-id <id> --store-id <rms_id> --user-id <user> --format json
+adp memory binding get --space-id <id> --app-id <app> --format json
+```
+
+`referencedApps` 不总是准确，判断某个应用用哪个库要看 `memory binding get`。
+
+## 写入
+
+先 `--dry-run` 预览，再执行。
+
+```bash
+adp memory create --space-id <id> --name 客服长期记忆 --format json            # 默认 rich、开摘要
+adp memory create --space-id <id> --name 会话缓存 --type flat --ttl-days 30 --format json
+adp memory entry add --space-id <id> --store-id <store> --user-id <user> --text "<≤4000 字>" --format json
+adp memory entry update --space-id <id> --store-id <store> --user-id <user> --entry-key <key> --content "<新内容>" --format json
+adp memory bind --space-id <id> --app-id <app> --store-id <store> --format json
+adp memory binding update --space-id <id> --app-id <app> --disable --format json
+```
+
+- rich 库 `entry add` 会用模型从文本生成条目名称（就是 entry key）和 front matter；写完用 `entry list` 取真实 key，不要自己猜。
+- `entry update`/`entry delete` 会自动读取当前版本；flat 条目只能改 `--content`/`--type`。
+- 一个应用每种类型最多一个绑定。`bind` 已有绑定时会切换到新库；不传 `--store-id` 时平台自动建默认库。没有解绑接口，停用用 `binding update --disable`。
+- `memory summary set --user-id <user> --text "<完整摘要>"` 是整份覆盖，不是追加；`--text` 必填，先 `memory summary get` 取现有内容再改。
+
+## 删除
+
+`memory delete`、`entry delete`、`summary delete` 都需要用户明确同意后才加 `--yes`。
+删除库会连同所有条目一起删除，不可恢复；应用仍启用绑定时报 `MemoryStoreInUse`，要先切换或停用绑定，不要擅自去改用户应用的绑定。
+
+## 导入导出
+
+```bash
+adp memory export --space-id <id> --store-id <store> --output ./memory.csv --format json
+adp memory import --space-id <id> --store-id <store> --file ./memory.csv --format json
+```
+
+CSV 列与导出一致：rich 为 `UserId,Name,Type,Frontmatter,Content`，`Type` 写标签（如 `user`），不是数字；flat 为 `VisitorId,Type,Content`。
+导入失败报 `MemoryImportFailed`，平台不给逐行原因，先对照一份导出的 CSV 检查列名和类型。导入的 rich 条目名称可能被模型改写。

package/skills/adp/references/operations.md

@@ -0,0 +1,56 @@
+# 运营数据、用量、审计与模型目录
+
+都是只读命令，唯一的例外是 `corp assistant set`。时间窗口用 `--from` / `--to`，可以写 `YYYY-MM-DD`（按北京时间）、ISO 时间或 Unix 秒；不传就是最近 7 天。
+
+```bash
+adp metrics overview --space-id <id> --format json      # 工作台活跃人数、会话数、运行时长，以及环比
+adp metrics trend --space-id <id> --from 2026-10-01      # 每天的运行时长
+adp metrics top-users --space-id <id> --limit 10         # 按任务数排行的用户；超过 --limit 时 truncated=true
+adp metrics detail --space-id <id> [--pu]                # 每个用户的统计；加 --pu 看每次运行的 PU 和 token
+adp metrics app --app-id <id> --space-id <id>            # 单个应用的调用量、成功率、耗时、回复类型分布
+adp metrics export --space-id <id> --yes                 # 只提交导出；文件发到控制台通知，没有可轮询的任务
+
+adp billing resources --space-id <id>                    # 套餐和增值包的总量与已用量
+adp billing summary|detail|consumption|concurrency --space-id <id> [--app-id <id>]
+
+adp audit meta                                            # --action / --biz 可取的值
+adp audit list --space-id <id> --action delete --limit 20 # 最新的在前；游标分页：truncated=true 时按 next_actions 带 --cursor 续翻，传 --page 报 UsageError
+adp account list --space-id <id>
+
+adp corp assistant get --space-id <id>                    # 工作台设置：长期记忆、自定义指令、默认模型
+adp portal get                                            # 企业门户的状态和子域名
+
+adp models --space-id <id> [--scene 18] --fields modelId,name   # 空间可用模型列表；--scene 18 只列 Claw 模式可用的
+adp models get --model-id TCADP/glm-5.1                   # 完整模型卡片
+adp models developers --space-id <id> [--limit 10 --page 0]   # 列表 envelope：items / truncated / total；--page 从 0 开始
+adp models mappings --model TCADP/glm-5.1                 # 已下线的模型名现在会路由到哪个模型
+
+adp workspace credential --workspace-id <id> [--reveal]   # 会话沙箱的存储凭证，默认打码
+adp workspace download-url --workspace-id <id> --path /workdir/x.md [--reveal]
+```
+
+- `billing summary|detail|consumption|concurrency` 和 `account list` 需要企业管理员授予报表权限，否则返回 `PermissionDenied`。这时告诉用户去找管理员，不要换账号重试。
+- PU 消耗有两个来源：工作台按次运行的 PU 用 `metrics detail --pu`；整个空间或单个应用的资源消耗（含 PU）用 `billing consumption`（需要报表权限）。`metrics overview`、`trend`、`top-users` 只统计工作台的任务和会话，不含 PU。
+- `--action` / `--biz` 必须是 `adp audit meta` 里的 key（如 `modify`、`app`），写中文名或拼错会直接报参数错误。
+- `usage` 和 `billing … --app-id` 遇到 450002 时，CLI 会先查应用：应用不存在报 `AppNotFound`，存在才是 `PermissionDenied`。
+- 不存在的资源统一报 not_found（退出码 3）并带专门的 code：应用 450011「应用不存在」→ `AppNotFound`，插件 460010「插件不存在」→ `PluginNotFound`，技能 450002「技能不存在」→ `SkillNotFound`；next_actions 指向对应的 list 命令。460010 也用于「会话不存在或没有操作权限」，报 `ConversationNotFound` / not_found。其他映射：450403「ErrAppNotFound」、460004「机器人不存在」→ `AppNotFound`；450151「标签标准词不存在」→ `KbLabelNotFound`；450013「QA不存在」→ `KbQaNotFound`；471044「ErrConflictQuestionNotFound」→ `KbQaConflictNotFound`；440014「生成任务不存在」→ `GuidelineTaskNotFound`；450160「QA无法编辑」→ `KbQaNotEditable`（conflict，可重试，问答还在审核/学习中）。CLI 改写过的错误（如 `TimerTaskNotFound`、`CredentialNotFound`）在 message 末尾括号里保留平台原始码。
+- 删除不存在的 ID 时，平台的删除接口常常照样返回成功，所以 CLI 先只读地查一遍：`kb doc/file/qa/label delete`、`channel delete`、`synonym delete`、`agent delete` 有任何一个 ID 不存在（`--dry-run` 也先查）就报对应的 `KbDocNotFound` / `KbQaNotFound` / `KbLabelNotFound` / `ChannelNotFound` / `SynonymNotFound` / `AgentNotFound`（退出码 3），一条都不删。`plugin delete` 对不存在的插件平台报 460001 FailedOperation，带 `--space-id`（或 adp.jsonc 有空间）时 CLI 用 DescribePlugin 确认后报 `PluginNotFound`。`guideline delete` 同样先逐个查：任何一个 ID 不存在就报 `GuidelineNotFound`（退出码 3），一条都不删；ID 都存在但平台仍拒绝时才是 `GuidelineBatchFailed`。
+- 数字 ID 在本地统一校验，所有命令（含 `--dry-run`）都一样：`--app-id`、`--kb-id`、`--channel-id`、`--release-id`，以及 `adp kb` 下的 `--qa-id`、`--doc-id`、`--label-id`。传名称或 `doc-1` 这类值报 `InvalidIdFormat`（退出码 2），不发请求，next_actions 指向能查到数字 ID 的列表命令。逗号分隔或重复传的每一项都要是数字。
+- 只接受一个 ID 的参数（`--agent-id`、`--plugin-id`、`--app-id` 等）传了逗号或重复传，本地报 `UsageError`（退出码 2），不会拼成一个错误的 ID；要处理多个就逐个执行。`kb doc delete` / `kb file delete` 的 `--doc-id` 可以重复传或逗号分隔，删除是全有或全无。
+- 删除后再读：`kb doc get` / `kb file get` 对已删除的文档平台仍返回成功但内容为空，CLI 报 `KbDocNotFound`（退出码 3）；`kb doc retry` 遇到已删除文档（450202）同样报 `KbDocNotFound`，next_action 是 `adp kb doc list --kb-id <id>`。`agent get` 对已删除的智能体平台报 `550005 数据不存在`，CLI 报 `AgentNotFound`（退出码 3）。
+- not_found 错误的 message 会去掉平台附带的「请重试」（例如「插件不存在，请重试」），重试找不回已删除的资源。
+- 失败时的 next_actions：「without --yes」类用法错误给出加上 `--yes` 的原命令（会真的写入）；`PermissionDenied`（450002）给出 `adp whoami --format json`，请空间管理员授权；可重试错误（如 450003）第一条一定是原命令（带上从 adp.jsonc 解析出的 `--app-id`），后面可能再附一条查 ID 的命令；只有参数/用法错误才回退到 `adp schema`。缺少 `--space-id` / `--app-id` 又没有 adp.jsonc 时，给出能查到这个 ID 的命令（`--all-spaces`、`adp space list`、`adp app list --all-spaces`）。
+- 写命令 `--dry-run` 成功且没有别的建议时，next_action 是去掉 `--dry-run` 的同一条命令（需要确认的加 `--yes`）。
+- `kb search` 结果带 `truncated`，没有 `total`（命中数等于 `--limit` / `--recall-count` 时 truncated=true；接口不能分页，不接受 `--page`，续查是加大 `--limit`）；`skill refs` 带 `total` / `truncated`；`metrics top-users` 是 `items` + `total` / `truncated` / `page` / `pageSize`，续查保留 `--limit`、`--page` 加一（排名一次取回，本地切页）。`agent list` 每行都有 `name`。`agent changed --since 0` 表示从头算。`--variable-id` 只接受一个 ID。
+- 缺 `--space-id` / `--app-id` 的用法错误，next_action 是 `adp space list` / `adp app list --all-spaces`，不是 schema。`conversation messages` 对 `adp chat` 的会话（type 5）报 `ConversationNotFound`，next_action 指向 `adp tail`。
+- `app key list`、`agent changed`、`models developers` 返回标准列表 envelope，支持 `--limit` / `--page`；列表续取的 next_action 保留原命令的全部参数（含 `--fields`、`--env`、`--profile`、`--config`）。
+- `channel get` 的报错按哪个 id 不对而不同（实测）：应用 id 不存在时平台返回 450003「无坐席权限」，CLI 报 `PermissionDenied`，和真正缺席位同一个码，先用 `app get` 确认应用存在再找管理员；应用存在而渠道 id 不存在时是 4506001「渠道不存在」→ `ChannelNotFound`（next_actions 指向 `channel list`）；`--channel-id 0` 是 450057「参数错误」；非数字 id 报 `InvalidIdFormat`。
+- `next_actions[].command` 都可以原样执行：不含 `<占位符>` 和说明文字，会带上你传过或从 adp.jsonc 解析出的 `--space-id` / `--app-id` / `--agent-id` / `--kb-id`。需要你补的值写在 `reason` 里。
+- `channel list|create` 偶尔返回 450003（无席位权限）后重试又成功：CLI 报 `PermissionDenied`，`retryable: true`，提示可能是瞬时的。重试一次；持续出现才找空间管理员分配席位。
+- 只读命令加 `--dry-run` 无论成功还是失败都会带 `DryRunIgnored` warning（例如没有报表权限的 `billing summary`）。
+- `docs list` 一次拿到整个目录，结果带 `total`，`truncated` 按 `items.length < total` 计算。
+- `trigger get|list` 的 `status` 是数字；`agent limits` 的字段是 camelCase（如 `agentToolLimit`）。
+- 列表的续页 next_actions（`--limit` / `--page`）会带上你传过的范围参数（`--space-id`、`--app-id`、`--kb-id`、`--query` 等），直接照抄执行即可。
+- `corp assistant set` 会改动该空间所有成员的工作台。执行前先 `get` 一次，把要改的字段告诉用户，得到同意后再加 `--yes`。
+- `workspaceId` 来自 `adp conversation get` 的返回结果，只有带沙箱的会话才有。`workspace credential` 对不存在的工作区、或 `--type` / `--app-id` 与会话不符时报 `WorkspaceNotFound`。凭证和下载链接默认打码；只有用户需要把它们交给别的工具时才加 `--reveal`，而且不要在对话里转述明文。
+- 席位分配、资源包明细、已消耗模型这几项，目前平台后端还没开放，CLI 也没有对应命令。开通门户在控制台完成。