@tencentcloudadp/cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,41 @@
+# AppKey 与分享
+
+AppKey 是终端用户通道（SSE / WebSocket 对话、分享页）调用应用时用的密钥。应用发布过一次才会有 key。
+
+```bash
+adp app key get --app-id <id> --format json            # 默认打码：前4位…后4位
+adp app key get --app-id <id> --reveal --format json   # result.appKey 是完整明文
+adp app key list --app-id <id> --reveal
+```
+
+- 用户要拿 key 去集成时用 `--reveal`。拿到后直接交给用户或写入用户指定的环境变量，不要回显到日志、提交到仓库或贴进对话摘要。
+- 启停、删除用 `--key <后4位以上>` 指定，不需要粘贴完整 key：`adp app key disable --key Wezw`。
+- 应用至少保留一个启用的 key（`AppKeyLastEnabled`）。`disable` / `delete` 在 `--dry-run` 时也会先读 key 列表，最后一把启用的 key 直接报这个错。轮换时先 `create`，再禁用旧的。
+- `create` 报 `AppKeyNotCreated` 表示平台没保存新 key（部分账号只允许一个 key），继续用现有 key。
+- 查一个 key 属于哪个应用：`printf %s "$KEY" | adp app key lookup --stdin`。
+- `adp chat` 会自动读取 AppKey，不需要手动传。
+
+## 分享
+
+```bash
+adp app share-url --app-id <id> --yes --format json     # result.shareUrl：公开对话链接
+adp conversation share create --app-id <id> --record-id <提问记录ID> --record-id <回复记录ID>
+adp conversation share get --share-id <id>
+adp app shared list --space-id <id> --query 助手          # 企业共享应用目录
+```
+
+- `share-url` 每次都会换一条新链接，旧链接可能失效。只在用户要链接时调用，并告诉用户之前的链接可能不能用了。
+- 分享会话没有删除接口，拿到分享 ID 的人都能看。分享前和用户确认内容可以公开。
+- 记录 ID 来自对话流：提问和回复各有一个 `RecordId`。快照里 `type: "thought"` 是模型思考，展示给用户时通常跳过。
+
+## A2A 地址
+
+```bash
+adp app a2a-url --app-id <id> --format json               # 默认打码
+adp app a2a-url --app-id <id> --refresh --yes --reveal    # 生成或轮换，旧地址立即失效
+```
+
+发布后 A2A 地址不会自动生成：没跑过 `--refresh` 时 `a2a-url` 返回空的 `a2aUrl`（`generated: false`），这不是发布失败。第一次需要 `--refresh --yes` 生成；之后再 `--refresh` 会轮换地址，旧地址立即失效，所以只在第一次或用户明确要轮换时用。
+
+- A2A 地址里的 `agt_…` 段等同凭证，和 AppKey 一样：只在用户要接入时才 `--reveal`，不要写进日志或回复里的其他地方。
+- 必须先 `adp deploy` 发布，否则报 `AppNotReleased`。轮换会让已接入的调用方失效，先问用户。

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

@@ -0,0 +1,36 @@
+# Application modes (`adp init --app-mode`)
+
+Integer enum on `CreateApp` / `adp.jsonc` `app_mode`:
+
+| `app_mode` | Name | Instructions live on | Mount Skills | Typical use |
+| ---: | --- | --- | --- | --- |
+| 1 | Standard | App-level `role_description` | No | FAQ / knowledge QA. No `agent_id`; `CreateAgent` is rejected. A query that matches no workflow (or knowledge) is answered by the model under `role_description`, not by a fallback workflow — write the fallback behaviour into `role_description`. |
+| 2 | Multi-Agent (`adp init` default) | Agent `Instructions` (`ModifyAgent`) | No | Team + handoff / workflow orchestration |
+| 3 | Single workflow | App-level role description | No | Fixed pipeline, lowest token |
+| 4 | Claw | App-level role description | **Yes** | Autonomous coding / general agent |
+
+## Switching
+
+- `1` / `2` / `3` can switch among themselves via `ModifyApp` / `adp app update` (mode change is not a v1 flag; create a new app if unsure).
+- **Claw (`4`) is isolated.** Switching an existing app into or out of Claw requires a **new** app.
+
+## Two layers (easy to mix up)
+
+1. **Application mode** = `app_mode` on the app (this table).
+2. **Collaboration sub-mode** = only inside `app_mode=2`. Set `mode.multi_agent.collaboration_mode` in `adp.jsonc`: `1` free-handoff, `2` workflow orchestration, `3` Plan-and-Execute. That is **not** `--app-mode`.
+
+## AgentSpec
+
+- Claw (`4`) only releases with a Claw-scene model: `adp models --scene 18 --space-id <id> --format json`. Any other `agent.model.model_id` fails `adp deploy` with `4600005`. Details: [pitfalls.md](pitfalls.md).
+- `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`.
+- 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`
+  first and push the complete target set. Ids are plain numeric strings, no `kb_`
+  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)
+  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.

package/skills/adp/references/auth.md

@@ -0,0 +1,45 @@
+# 鉴权与站点
+
+先 `adp auth status --format json` 查看 `profile/site/endpoint/source`。
+`adp auth list --format json` 查看已存 profile。不要读取凭据文件内容到上下文。
+
+- 公有云 `cloud` 的 CAM SecretId 以 AKID 开头，入口 https://console.cloud.tencent.com/cam/capi。
+- 独立站 `independent` 使用 OneID，不要求 AKID 前缀；登录时显式 `--site independent`。
+- 自定义站点使用 `--site custom --endpoint <host>`，先确认用户提供的目标地址。
+- `--profile` 优先于 `ADP_PROFILE` 和 active profile，但环境凭据仍优先于 profile 中的凭据。
+  根据 `source` 验证实际身份，不凭参数猜测。profile 存于 `~/.adp/profiles/`，权限 0600。
+
+已有 profile 时无需重新登录。
+
+## 在对话里完成首次登录（WorkBuddy 等 agent 环境）
+
+```bash
+adp auth login --web --detach --format json   # 返回 result.url / expiresAt / pid
+adp auth status --format json                 # 轮询，直到 ok:true
+```
+
+- 页面只监听 `127.0.0.1`，链接带一次性 token，默认 5 分钟过期（`--timeout <秒>` 调整，最长 1800）。
+- 页面先用一次只读调用校验密钥，校验失败会在页面上提示并允许重填，不会保存无效密钥。
+- 用户关闭页面或过期后重新执行一次 `--web --detach`；不要改为在对话中收集密钥。
+- `--site independent` / `--profile <name>` 可与 `--web` 同用；`--open` 会尝试直接打开浏览器。
+
+## 在终端或 CI 登录
+
+需要登录时让用户通过受保护的本地环境设置
+`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 缺凭据时退出，不等待交互输入；提示用户在本地完成安全配置。
+
+## 只有一套凭据
+
+所有命令（含 `adp workflow`、`adp kb doc`）都只用 CAM SecretId/SecretKey，没有 Tool Key。
+`adp workflow` 和 `adp kb doc import` 会调用 LKE 2023-11-30 接口，只支持公有云站点；
+鉴权失败时先看 `auth status` 的 `source`，再让用户确认 CAM 策略含 ADP 与 LKE 权限。
+不要反复登录，不要换应用绕过权限。
+`adp env list --format json` 只列环境变量名称和敏感标记，不返回值。

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

@@ -0,0 +1,159 @@
+{
+ "ProtoVersion": "V2_6",
+ "WorkflowID": "",
+ "WorkflowName": "zz-demo-branch",
+ "WorkflowDesc": "Reply BR-YES when the query contains yes, otherwise BR-NO",
+ "Nodes": [
+  {
+   "NodeID": "start",
+   "NodeName": "Start",
+   "NodeDesc": "",
+   "NodeType": "START",
+   "StartNodeData": {},
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": [
+    "logic1"
+   ]
+  },
+  {
+   "NodeID": "logic1",
+   "NodeName": "判断",
+   "NodeDesc": "",
+   "NodeType": "LOGIC_EVALUATOR",
+   "LogicEvaluatorNodeData": {
+    "Group": [
+     {
+      "Logical": {
+       "LogicalOperator": "UNSPECIFIED",
+       "Compound": [],
+       "Comparison": {
+        "Left": {
+         "InputType": "SYSTEM_VARIABLE",
+         "SystemVariable": {
+          "Name": "SYS.UserQuery"
+         }
+        },
+        "LeftType": "STRING",
+        "Operator": "CONTAINS",
+        "Right": {
+         "InputType": "USER_INPUT",
+         "UserInputValue": {
+          "Values": [
+           "yes"
+          ],
+          "FileNames": []
+         }
+        },
+        "MatchType": "PRECISE"
+       }
+      },
+      "NextNodeIDs": [
+       "ans_yes"
+      ]
+     },
+     {
+      "NextNodeIDs": [
+       "ans_no"
+      ]
+     }
+    ]
+   },
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": []
+  },
+  {
+   "NodeID": "ans_yes",
+   "NodeName": "ans_yes",
+   "NodeDesc": "",
+   "NodeType": "ANSWER",
+   "AnswerNodeData": {
+    "Answer": "BR-YES"
+   },
+   "Inputs": [],
+   "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": "ans_no",
+   "NodeName": "ans_no",
+   "NodeDesc": "",
+   "NodeType": "ANSWER",
+   "AnswerNodeData": {
+    "Answer": "BR-NO"
+   },
+   "Inputs": [],
+   "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": [],
+   "NextNodeIDs": []
+  }
+ ],
+ "Mode": "NORMAL"
+}

package/skills/adp/references/canvas/deep-research.json

@@ -0,0 +1,267 @@
+{
+ "ProtoVersion": "V2_6",
+ "WorkflowID": "",
+ "WorkflowName": "deep-research-main",
+ "WorkflowDesc": "Deep research: plan, research, summarize the user question",
+ "Nodes": [
+  {
+   "NodeID": "start",
+   "NodeName": "Start",
+   "NodeDesc": "",
+   "NodeType": "START",
+   "StartNodeData": {},
+   "Inputs": [],
+   "Outputs": [],
+   "NextNodeIDs": [
+    "ref_plan"
+   ]
+  },
+  {
+   "NodeID": "ref_plan",
+   "NodeName": "拆解问题",
+   "NodeDesc": "",
+   "NodeType": "WORKFLOW_REF",
+   "WorkflowRefNodeData": {
+    "WorkflowID": "<PLAN_WORKFLOW_ID>",
+    "RefInputs": [
+     {
+      "Name": "topic",
+      "Type": "STRING",
+      "Input": {
+       "InputType": "SYSTEM_VARIABLE",
+       "SystemVariable": {
+        "Name": "SYS.UserQuery"
+       }
+      }
+     }
+    ]
+   },
+   "Inputs": [],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [
+      {
+       "Title": "result",
+       "Name": "result",
+       "Type": "STRING",
+       "Required": [],
+       "Properties": [],
+       "Desc": "",
+       "AnalysisMethod": "COVER"
+      }
+     ],
+     "Desc": "Output content",
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": [
+    "ref_research"
+   ],
+   "ExceptionHandling": {
+    "Switch": "OFF",
+    "MaxRetries": "3",
+    "RetryInterval": "1",
+    "AbnormalOutputResult": "",
+    "HandleMethod": "EXCEPTION_OUTPUT",
+    "NextNodeIDs": [],
+    "AbnormalRetrySwitch": "ABNORMAL_RETRY_ON",
+    "Timeout": "0"
+   }
+  },
+  {
+   "NodeID": "ref_research",
+   "NodeName": "检索研究",
+   "NodeDesc": "",
+   "NodeType": "WORKFLOW_REF",
+   "WorkflowRefNodeData": {
+    "WorkflowID": "<RESEARCH_WORKFLOW_ID>",
+    "RefInputs": [
+     {
+      "Name": "topic",
+      "Type": "STRING",
+      "Input": {
+       "InputType": "REFERENCE_OUTPUT",
+       "Reference": {
+        "NodeID": "ref_plan",
+        "JsonPath": "Output.result"
+       }
+      }
+     }
+    ]
+   },
+   "Inputs": [],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [
+      {
+       "Title": "result",
+       "Name": "result",
+       "Type": "STRING",
+       "Required": [],
+       "Properties": [],
+       "Desc": "",
+       "AnalysisMethod": "COVER"
+      }
+     ],
+     "Desc": "Output content",
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": [
+    "ref_summarize"
+   ],
+   "ExceptionHandling": {
+    "Switch": "OFF",
+    "MaxRetries": "3",
+    "RetryInterval": "1",
+    "AbnormalOutputResult": "",
+    "HandleMethod": "EXCEPTION_OUTPUT",
+    "NextNodeIDs": [],
+    "AbnormalRetrySwitch": "ABNORMAL_RETRY_ON",
+    "Timeout": "0"
+   }
+  },
+  {
+   "NodeID": "ref_summarize",
+   "NodeName": "汇总结论",
+   "NodeDesc": "",
+   "NodeType": "WORKFLOW_REF",
+   "WorkflowRefNodeData": {
+    "WorkflowID": "<SUMMARIZE_WORKFLOW_ID>",
+    "RefInputs": [
+     {
+      "Name": "topic",
+      "Type": "STRING",
+      "Input": {
+       "InputType": "REFERENCE_OUTPUT",
+       "Reference": {
+        "NodeID": "ref_research",
+        "JsonPath": "Output.result"
+       }
+      }
+     }
+    ]
+   },
+   "Inputs": [],
+   "Outputs": [
+    {
+     "Title": "Output",
+     "Type": "OBJECT",
+     "Required": [],
+     "Properties": [
+      {
+       "Title": "result",
+       "Name": "result",
+       "Type": "STRING",
+       "Required": [],
+       "Properties": [],
+       "Desc": "",
+       "AnalysisMethod": "COVER"
+      }
+     ],
+     "Desc": "Output content",
+     "AnalysisMethod": "COVER"
+    }
+   ],
+   "NextNodeIDs": [
+    "answer1"
+   ],
+   "ExceptionHandling": {
+    "Switch": "OFF",
+    "MaxRetries": "3",
+    "RetryInterval": "1",
+    "AbnormalOutputResult": "",
+    "HandleMethod": "EXCEPTION_OUTPUT",
+    "NextNodeIDs": [],
+    "AbnormalRetrySwitch": "ABNORMAL_RETRY_ON",
+    "Timeout": "0"
+   }
+  },
+  {
+   "NodeID": "answer1",
+   "NodeName": "回复",
+   "NodeDesc": "",
+   "NodeType": "ANSWER",
+   "AnswerNodeData": {
+    "Answer": "MAIN:{{r}}"
+   },
+   "Inputs": [
+    {
+     "Name": "r",
+     "Type": "STRING",
+     "Input": {
+      "InputType": "REFERENCE_OUTPUT",
+      "Reference": {
+       "NodeID": "ref_summarize",
+       "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"
+}