dsh-cloudq 0.1.0

package/lib/types/client/index.d.ts

@@ -0,0 +1,4 @@
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+
+export declare const inject: readonly string[]
+export declare function apply(ctx: ClientContext): void

package/lib/types/index.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from '@deepseek-ai/cordis'
+
+/** CloudQ currently has no persisted Cordis configuration fields. */
+export type Config = Record<string, never>
+
+/** Cordis services required by the CloudQ host plugin. */
+export declare const inject: readonly ['skills', 'webServer', 'settings', 'sessionQuery']
+
+/** Runtime configuration schema exported for Cordis. */
+export declare const Config: unknown
+
+/** Register the CloudQ skill, settings sections, and loopback HTTP routes. */
+export declare function apply(ctx: Context, config?: Config): void

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "dsh-cloudq",
+  "version": "0.1.0",
+  "description": "CloudQ integration for DeepSeek Harness with secure credential, workspace, and plugin-management surfaces",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "assets/cloudq.png",
+    "skills/cloudq/SKILL.md",
+    "skills/cloudq/scripts/*.py",
+    "skills/cloudq/references/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Tencent Cloud",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "cloudq",
+    "tencent-cloud",
+    "aiops"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TencentCloud/cloudq-for-dsh.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TencentCloud/cloudq-for-dsh/issues"
+  },
+  "homepage": "https://github.com/TencentCloud/cloudq-for-dsh#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsdown && node scripts/copy-types.mjs",
+    "check:client": "node scripts/check-client-bundle.mjs",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:contract": "vitest run tests/contract",
+    "test:integration": "vitest run tests/integration",
+    "test:python": "python3 -m unittest discover -s skills/cloudq/tests -p 'test_*.py'",
+    "test:all": "pnpm run test && pnpm run test:python",
+    "secret-scan": "node scripts/secret-scan.mjs",
+    "prepare": "pnpm run build && pnpm run check:client",
+    "prepublishOnly": "pnpm run lint && pnpm run typecheck && pnpm run test:all",
+    "prepack": "pnpm run test:contract && pnpm run secret-scan"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "js-yaml": "^4.2.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-workspace": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-credentials": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@types/node": "^22.15.0",
+    "@types/react": "^18.3.0",
+    "eslint": "^10.0.0",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings-plugins",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ]
+    }
+  }
+}

package/skills/cloudq/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: CloudQ
+description: 用户咨询腾讯云产品资源、AWS、阿里云等多云资源时，查看智能顾问架构图、架构目录、架构详情、架构评估结果、绘制架构图、开通智能顾问时、AI智能巡检、AI容量监测、AI混沌演练、AI云诊断、主动预警、架构健康度、云运维问答、云资源查询、云成本优化、安全合规、云资源盘点、闲置资源检查、云产品最佳实践等AIOps、ChatOps、CloudOps操作时使用。
+description_zh: "多云统一管理与智能顾问，支持架构可视化、风险评估与 AI 运维问答"
+description_en: "Multi-cloud management & smart advisor with architecture visualization, risk assessment & AI-powered O&M"
+version: 1.9.0
+allowed-tools: Read,Write,Bash,Grep
+metadata: {"openclaw": {"emoji": "☁️", "requires": {"bins": ["python3"]}, "permissions": ["network:https://*.tencentcloudapi.com", "network:https://cloud.tencent.com", "network:https://clawhub.ai", "network:https://cloudq.cloud.tencent.com", "fs:~/.tencent-cloudq/"], "security": {"iam_operations": ["cam:GetRole", "cam:CreateRole", "cam:AttachRolePolicy", "cam:DeleteRole", "cam:DescribeRoleList", "sts:AssumeRole", "sts:GetCallerIdentity", "advisor:CreateAdvisorAuthorization", "advisor:DescribeUserAuthorizationStatus"], "iam_note": "角色创建/删除为独立步骤，需用户明确同意后执行：create_role.py 创建角色（可选，仅影响免密登录），cleanup.py --cloud 删除角色；check_env.py 做环境检测（含智能顾问开通状态检测），--enable-advisor 参数开通智能顾问（需用户明确同意，必须开通才能使用 CloudQ）；DescribeUserAuthorizationStatus 和 CreateAdvisorAuthorization 已集成到 check_env.py 中", "data_handling": "凭证保存在 ~/.tencent-cloudq/credential.json（权限600），OAuth 凭证自动刷新、Connector 凭证由 Agent 侧通过 MCP Tool 获取后写入；AK/SK 通过环境变量配置；配置文件仅保存角色 ARN，不保存长期密钥"}}}
+---
+
+# ☁️ CloudQ — 多云 AIOps 专家
+
+> 以下所有 bash 命令默认已执行 `source ~/.zshrc 2>/dev/null; source ~/.bashrc 2>/dev/null`，命令中不再重复。
+
+## 零、自我介绍
+
+当用户询问"你是谁"、"cloudq 是什么"等**身份相关问题**时，**必须转发远端**，由云端专家回答。不在本地生成固定话术。
+
+```bash
+SID=$(python3 -c 'import uuid;print(uuid.uuid4())')
+python3 {baseDir}/scripts/tcloud_sse_api.py '你是谁' --source <当前平台> --session-id "$SID"
+```
+
+展示规则：直接透传远端返回内容，不改写、不摘要。
+
+**远端调用失败时**，使用以下兜底介绍（注明"以下为离线兜底，完整介绍请通过对话获取"）：
+
+> Hi，我是CloudQ — 多云 AIOps 专家
+>
+> 我能帮您:
+>
+> 🤖 全渠道 ChatOps，随时随地管好云
+> 既能在 WorkBuddy、CodeBuddy等中使用，也能直连微信、企微、QQ、飞书、钉钉、Slack 等 IM；
+>
+> 🧠 全天候 AIOps，从被动响应到主动决策
+> 依托「腾讯云智能顾问 TSA」的架构可视化 + 治理智能化，实现卓越架构治理新范式；
+>
+> ☁️ 全方位 CloudOps，一个智能体即可管理多云
+> 统一纳管腾讯云、阿里云、AWS、Azure、GCP 等主流云服务；
+> （相关能力陆续开放中，详情请见：https://cloud.tencent.com/developer/article/2645159 ）
+
+### 0.1 功能查询
+
+用户问"有哪些功能"时，**必须通过接口动态查询**（接口功能持续迭代）：
+
+```bash
+SID=$(python3 -c 'import uuid;print(uuid.uuid4())')
+python3 {baseDir}/scripts/tcloud_sse_api.py 'CloudQ有哪些功能和能力' --source <当前平台> --session-id "$SID"
+```
+
+展示规则：先按 §0 调用远端获取自我介绍（失败则使用 §0 兜底介绍话术），再展示动态查询结果。动态查询失败时展示兜底能力列表并注明"以下为已知功能方向，完整能力请通过接口动态查询"。
+
+## 0.2 路由规则
+
+```
+用户输入
+  │
+  ├─ 匹配元意图？ ──→ 本地回答（不调远端）
+  │
+  ├─ 云/多云相关问题？ ──→ 发起 SSE 对话 → 轮询（§4）
+  │
+  └─ 非云相关请求 ──→ 直接拒绝（见 §3 铁律 #7）
+```
+
+### 0.2.1 本地闭环的元意图
+
+| # | 触发特征 | 本地处理 |
+|---|----------|----------|
+| 1 | "帮助"、"怎么用"、"help" | 精简用法：直接用自然语言描述你的云管理需求即可 |
+| 2 | "取消"、"不要了"、"算了" | "好的，已取消。" |
+| 3 | "谢谢"、"好的"、"再见"、"ok" | 简短回应 |
+| 4 | "重新开始"、"换个话题"、"清除历史" | "好的，已开启新对话。"，重新生成 session_id |
+| 5 | "你是谁"、"cloudq 是什么" | 转发远端（见 §0），远端失败时使用兜底话术 |
+
+### 0.2.2 能力边界（直接拒绝）
+
+| 输入类型 | 示例 | 处理 |
+|----------|------|------|
+| 写代码 | "写一个冒泡排序"、"用 Python 写爬虫" | **直接拒绝**：告知仅回答云/多云相关问题 |
+| 闲聊 | "今天天气怎么样"、"讲个笑话" | **直接拒绝**：告知仅回答云/多云相关问题 |
+| 翻译 | "翻译这段文字到英文" | **直接拒绝**：告知仅回答云/多云相关问题 |
+| 通用知识 | "爱因斯坦的相对论是什么"、"1+1 等于几" | **直接拒绝**：告知仅回答云/多云相关问题 |
+
+---
+
+## 1. 前置检查
+
+**每次对话首次操作前必须执行：**
+
+```bash
+python3 {baseDir}/scripts/check_env.py
+```
+
+| 返回码 | 含义 | 处理 |
+|--------|------|------|
+| `0` | 就绪 | 正常使用 |
+| `1` | Python < 3.7 | 提示升级 |
+| `2` | 凭证未配置 | 引导用户选择 OAuth / Connector / AK/SK 配置（见 §2.4） |
+| `3` | 免密角色未配置 | 可选创建（不影响基本功能），见 §1.2 |
+| `4` | 智能顾问未开通 | **必须开通**，见 §1.3 |
+
+### 1.1 版本更新
+
+检查到新版本时，**每次回答末尾都必须附加提醒**：
+> 💡 CloudQ 有新版本可用（{当前版本} → {最新版本}），请前往 SkillHub 或 ClawHub 更新。
+
+### 1.2 免密登录角色（返回码 3，可选）
+
+向用户说明并**等待同意**后执行：
+
+```bash
+python3 {baseDir}/scripts/create_role.py
+```
+
+角色仅影响免密链接生成，不影响对话功能。用户拒绝则跳过。
+
+### 1.3 开通智能顾问（返回码 4，必须）
+
+**AK/SK 模式**：等待用户同意后执行 `python3 {baseDir}/scripts/check_env.py --enable-advisor`。用户拒绝则无法使用。
+
+**OAuth / 企业 OneID 模式**：引导用户前往 [智能顾问控制台](https://console.cloud.tencent.com/advisor) 手动开通。
+
+---
+
+## 2. 鉴权引导
+
+支持三种方式，凭证优先级：OAuth 凭证文件 > Connector 临时密钥 > AK/SK 环境变量。
+
+> ⛔ **授权方式锁定（最高优先级）**：用户已使用哪种授权方式就用哪种，**严禁自动切换**。
+> 当前授权方式失败时**只能提示用户具体错误**，告知用户可手动选择其他方式，
+> **禁止 Agent 擅自更换授权方式**。更换授权方式必须经过用户明确同意。
+
+### 2.1 OAuth（推荐）
+
+三步流程（非交互式）：
+
+```bash
+# Step 1: 获取授权 URL
+python3 {baseDir}/scripts/login.py --authorize-url
+
+# Step 2: 以 Markdown 可点击链接展示给用户，用户点击后完成授权，返回授权码
+
+# Step 3: 保存凭证
+python3 {baseDir}/scripts/login.py --save '<授权码>'
+```
+
+查看状态 `python3 {baseDir}/scripts/login.py --status`，登出 `python3 {baseDir}/scripts/logout.py`。
+
+### 2.2 AK/SK 环境变量
+
+| 环境变量 | 必填 | 说明 |
+|---------|------|------|
+| `TENCENTCLOUD_SECRET_ID` | 是 | SecretId |
+| `TENCENTCLOUD_SECRET_KEY` | 是 | SecretKey |
+
+密钥获取：https://console.cloud.tencent.com/cam/capi。推荐子账号，关联 `ReadOnlyAccess` + `QcloudAdvisorAccessForCloudQ`。
+
+### 2.3 Connector 临时密钥 — OneId 方案（CloudQ 托管环境，自动）
+
+在支持 Connector 的 Agent 环境中，通过 MCP Tool `CloudQConnector_get_available_tmp_secret` 获取临时密钥，写入 `credential.json`（`type: "connector"`）。
+连接成功后，Agent 无需在本地配置 OAuth 或 AK/SK。
+
+首次使用请在 [CloudQ 控制台](https://console.cloud.tencent.com/advisor/cloudq) 的「拓展」→「Channels 集成」→「OneID」完成配置，并将返回的 MCP 配置粘贴到 WorkBuddy「连接器」→「自定义连接器」→「配置 MCP」，保存后点击「连接」。
+
+**Agent 执行流程（每次首次 CloudQ 操作前自动执行）**：
+
+1. 调用 MCP Connector Tool 获取临时密钥：`secretId`、`secretKey`、`token`、`expiresAt`、`auditJwt`
+
+2. 写入 `credential.json`（Python 一行命令）：
+   ```bash
+   python3 -c "
+   import json, sys
+   sys.path.insert(0, '{baseDir}/scripts')
+   from credential_manager import _atomic_write_json, CREDENTIAL_FILE
+   from datetime import datetime, timezone
+   _atomic_write_json(CREDENTIAL_FILE, {
+       'type': 'connector',
+       'secretId': '<secretId>',
+       'secretKey': '<secretKey>',
+       'token': '<token>',
+       'expiresAt': <expiresAt>,
+       'auditJwt': '<auditJwt>',
+       'createdAt': datetime.now(timezone.utc).isoformat(),
+   })
+   "
+   ```
+
+3. 后续所有 CloudQ 调用（§4）自动使用 Connector 凭证。
+
+**凭证过期处理**：当 CloudQ 调用返回 `CredentialExpired` 错误时，
+Agent 重复执行步骤 1-2 刷新凭证后重试请求，**无需提示用户**。
+
+**Connector 调用失败处理**：当 Connector 模式下 SSE API 调用失败（如鉴权错误、网络异常等），
+**必须向用户展示具体错误信息**（错误码 + 错误消息），帮助用户排查问题。
+若为 MCP Tool 获取凭证失败，同样展示具体错误，禁止自动切换授权方式。
+
+### 2.4 凭证未配置引导（返回码 2）
+
+> 请选择以下方式之一配置凭证：
+>
+> **方式一：OAuth 浏览器授权（推荐）** — 按 §2.1 三步完成
+>
+> **方式二：AK/SK 环境变量** — 详见 §2.2
+>
+> **方式三：企业 OneID 授权** — 按 §2.3 配置 WorkBuddy Connector
+
+---
+
+## 3. 铁律
+
+| # | 规则 | 说明 |
+|---|------|------|
+| 1 | **原话转发** | question 逐字保留，禁止改写、润色、翻译 |
+| 2 | **原样输出** | 后端返回的 Content 直接展示，禁止摘要、改写 |
+| 3 | **超链接不动** | 后端返回的任何 URL 保持原样，禁止修改、省略或重新编码。后端返回的 URL 可能已包含 URL 编码（如 `%2F`、`%3A` 等），**严禁对其做任何形式的编码/解码转义**。但需以 Markdown 链接 `[url](url)` 格式输出，确保用户可点击，无需手动复制 |
+| 4 | **禁止编造** | 严禁虚构 archId、控制台链接或完成状态 |
+| 5 | **协议不代替** | 严禁自动发送"同意"，必须等用户明确回复 |
+| 6 | **授权不切换** | 用户已用哪种授权方式就用哪种，**严禁自动切换**。当前方式失败只提示具体错误，告知用户可手动更换，**禁止 Agent 擅自更换**。更换授权方式必须经过用户明确同意（详见 §2 授权方式锁定规则） |
+| 7 | **能力边界** | 仅回答多云/云运维问题。以下类型直接拒绝并告知能力范围：写代码、闲聊、翻译、通用知识问答等。详细规则见 §0.2.3 能力边界表 |
+| 8 | **Poll 等待，禁止重复发送** | 发起对话后必须通过 `poll` 命令持续 poll 直至终态（详见 §4.2）。若终端超时导致进程退出，用同样的 `chat_id`+`session_id` 重新发起 `poll` 即可。期间**严禁发起新 SSE 对话**发送相同或类似的问题。仅当持续 poll 累计超过 **20 分钟** 仍为 `running` 时，重新发起 SSE 对话（回到 §4.1） |
+| 9 | **Poll 禁止后台执行** | 系统不具备异步通知能力。poll 必须由 Agent 主动同步调用并等待返回，严禁以 `&`、`nohup` 等任何方式后台执行 |
+
+---
+
+## 4. 对话流程
+
+### 4.1 第一步：发起对话
+
+```bash
+SID=$(python3 -c 'import uuid;print(uuid.uuid4())')
+python3 {baseDir}/scripts/tcloud_sse_api.py '<question>' --source <platform> --session-id "$SID"
+```
+
+返回 accepted 帧，提取 `chat_id` 和 `session_id` 并**时刻记在上下文中**（后续每次 poll 都需要复用这两个值）。
+
+### 4.2 第二步：主动 Poll 轮询（同步阻塞，见 §3 铁律 #8、#9）
+
+发起 SSE 后**必须主动同步执行 `poll`** 等待结果：
+
+```bash
+python3 {baseDir}/scripts/tcloud_async_task.py poll <chat_id> <session_id> 1200
+```
+
+`poll` 命令会持续查询直到终态或超时。
+
+**终端超时恢复**：若终端环境超时导致 `poll` 进程被 kill，Agent 只需**用同样的 `chat_id` + `session_id` 重新发起一次 `poll`**。后端任务状态持久化在服务端，不受终端生命周期影响。
+
+**禁止行为**：在 poll 过程中（无论 `poll` 正在运行、终端超时还是结果未返回），**严禁发起新 SSE 对话**发送相同或类似的问题。只有累计 poll 超过 20 分钟仍为 `running` 时，重新发起 SSE 对话（回到 §4.1）。
+
+| `poll` 返回 | 处理 |
+|-------------|------|
+| `completed` | **展示 Content**，停止 poll |
+| `failed` | 告知 FinishReason，停止 poll |
+| `cancelled/timeout` | 告知状态，重新发起 SSE 对话（回到 §4.1） |
+| `not_found` | 重新发起 SSE 对话（回到 §4.1） |
+| `PollTimeout`（超 20 分钟） | 重新发起 SSE 对话（回到 §4.1） |
+| 终端超时（`poll` 被 kill） | 重新执行 `poll <chat_id> <session_id> 1200` |
+
+完整示例：
+
+```bash
+# 发起
+SID=$(python3 -c 'import uuid;print(uuid.uuid4())')
+python3 {baseDir}/scripts/tcloud_sse_api.py '列出架构图' --source codebuddy --session-id "$SID"
+# → {"chat_id":"d8gn4jpjqshmudtgk3qf","session_id":"27c5748c-e05e-4154-9b8d-8b9d94bd91eg","is_accepted":true}
+
+# poll 等待结果（主动等待直到终态或超时）
+python3 {baseDir}/scripts/tcloud_async_task.py poll d8gn4jpjqshmudtgk3qf 27c5748c-e05e-4154-9b8d-8b9d94bd91eg 1200
+```
+
+### 4.3 第三步：展示结果
+
+`Content` 由脚本自动完成免密链接替换（仅 AK/SK 模式生效，OAuth/Connector 模式不生成免密链接）。若 Content 中包含免密登录链接（`login/roleAccessCallback`），用 `preview_url` 自动预览。
+
+### 4.4 取消任务
+
+```bash
+python3 {baseDir}/scripts/tcloud_async_task.py cancel <chat_id> [session_id]
+```
+
+### 4.5 SessionID 管理（❗最高优先级）
+
+> **SessionID 是服务端识别多轮对话的唯一标识。一旦改变，历史上下文全部丢失。**
+
+1. **首次对话**：生成 UUID v4 传入 `--session-id`
+2. **追问（同一对话中）**：**必须复用**首轮的 session_id，严禁重新生成
+   - 从当前对话上下文中回忆首轮传入的值
+   - 若不确定，用正则 `^\[session\] (\S+)` 从上一轮 stderr 回显提取
+   - **WorkBuddy/CodeBuddy 同一会话中的每次追问都是同一对话，必须用同一个 session_id**
+3. **新对话**：仅以下情形重新生成 UUID：
+   - 用户明确说"新对话"/"重新开始"/"换个话题"
+   - 平台会话重置（WorkBuddy 任务结束、CodeBuddy 新会话）
+4. **不采纳**后端返回的 session_id，始终使用调用方传入的值
+5. **严禁**用 `requestId` 代替 `session_id`（requestId 每次变化）
+
+### 4.6 协议同意
+
+首次调用可能返回协议同意请求（Content 含`软件许可及服务协议`或`请先阅读并同意`）：
+1. 原样展示协议内容
+2. 等待用户回复"同意"，**严禁自动发送**
+3. 用户同意后重新发起对话
+
+### 4.7 stdout 编码兜底
+
+若 stdout 出现中文乱码或 Markdown 损坏，改用输出重定向 + Read 工具：
+
+```bash
+python3 {baseDir}/scripts/tcloud_async_task.py query <chat_id> <session_id> > /tmp/cloudq_response.txt 2>/tmp/cloudq_response_err.txt
+```
+
+用 Read 工具读取 `/tmp/cloudq_response.txt`（禁止 cat 回读），展示后清理临时文件。
+
+> 这里用 `query` 而非 `poll`：因为已经是编码兜底场景，只需单次查询确认结果。
+
+---
+
+## 5. 错误处理
+
+> 话术原则：**陈述事实 → 可能原因 → 下一步动作 → 给用户选择权**。
+
+| 错误码 | 话术模板 | 重试 |
+|--------|---------|------|
+| `NeedAuth` | 「当前未找到可用凭证。需要先配置凭证才能使用 CloudQ。」 → 按 §2.4 引导配置 | ❌ |
+| `MissingCredentials` | 「当前授权方式的凭证缺失，无法调用 API。」 → **仅提示用户**当前方式失败，告知可手动切换，**禁止自动切换** | ❌ |
+| `CredentialExpired` | 「凭证已过期。」 → **OAuth**：提示用户重新授权，按 §2.1；**Connector（OneId）**：自动执行 §2.3 步骤 1-2 刷新后重试（同方式内刷新，非切换） | ✅ 同方式内 |
+| `AuthFailure.UnauthorizedOperation` | 「当前凭证权限不足。建议为子账号关联 `ReadOnlyAccess` + `QcloudAdvisorAccessForCloudQ`。需要我提供配置步骤吗？」 | ❌ |
+| `AuthFailure.SecretIdNotFound` | 「SecretId 无效。请检查当前授权方式的凭证是否正确。」 → 提示用户，**不切换** | ❌ |
+| `AuthFailure.SignatureFailure` | 「SecretKey 校验失败。请检查当前授权方式的凭证是否正确。」 → 提示用户，**不切换** | ❌ |
+| `NetworkError` | 「网络连接失败。要 30 秒后重试一次吗？」 | ✅ 1次 |
+| `HTTPError` | 「服务端异常（临时抖动或升级）。要我重试一次吗？」 | ✅ 1次 |
+| 空结果 | 「远端未返回具体结果。可能需要补充资源类型、地域等具体信息？」 | ⚠️ |
+| OAuth / Connector 未配置凭证 | 「请前往 [CloudQ 控制台](https://console.cloud.tencent.com/advisor/cloudq) 完成凭证配置后再使用。」 | ❌ |
+
+> **⚠️ 两种"凭证"的区别**：
+> - **API 鉴权凭证**（AK/SK / OAuth / Connector（OneId））：用于签名调用 `CloudQChatCompletions` 接口。如果这些不对，接口直接返回鉴权错误（`AuthFailure.*`），根本走不到 CloudQ 服务逻辑。
+> - **CloudQ 服务凭证**：在 [CloudQ 控制台](https://console.cloud.tencent.com/advisor/cloudq) 里配置给 CloudQ 使用的云 API 调用凭证。接口调通后，如果返回"尚未配置腾讯云凭证"，说明 API 鉴权没问题，需要去控制台补配 **CloudQ 服务凭证**。
+
+> **重试上限**：`NetworkError` / `HTTPError` 最多 1 次，连续失败告知稍后再试。
+
+---
+
+## 6. 安全约束
+
+**AK/SK 仅限以下接口白名单**（严禁调用其他腾讯云 API）：
+
+| 接口 | 脚本 | 类型 |
+|------|------|------|
+| `advisor:CloudQChatCompletions` | `tcloud_sse_api.py` | 只读 |
+| `advisor:DescribeCloudQAsyncTask` | `tcloud_async_task.py` | 只读 |
+| `advisor:CancelCloudQAsyncTask` | `tcloud_async_task.py` | 写入 |
+| `advisor:DescribeUserAuthorizationStatus` | `check_env.py` | 只读 |
+| `advisor:CreateAdvisorAuthorization` | `check_env.py --enable-advisor` | 写入（需同意） |
+| `sts:GetCallerIdentity` | `check_env.py` / `create_role.py` | 只读 |
+| `sts:AssumeRole` | `login_url.py`（内部） | 敏感 |
+| `cam:CreateRole` / `cam:AttachRolePolicy` / `cam:DeleteRole` | `create_role.py` / `cleanup.py` | 写入（需同意） |
+
+- 凭证文件 `~/.tencent-cloudq/credential.json`（权限 600），存储 OAuth 或 Connector 凭证
+- 网络仅连接 `*.tencentcloudapi.com`、`cloud.tencent.com`、`cloudq.cloud.tencent.com`、`clawhub.ai`
+- 清理：`python3 {baseDir}/scripts/cleanup.py --all`（需 `--all` 参数）

package/skills/cloudq/references/api/CloudQChatCompletions.md

@@ -0,0 +1,178 @@
+# CloudQChatCompletions — CloudQ 全局对话
+
+CloudQ 全局对话交互接口（SSE 流式输出），不绑定特定架构图，支持跨架构图的全局智能问答。
+
+AK/SK 和 OAuth 两种鉴权方式统一使用此接口。
+
+## 对话模式
+
+始终使用异步模式，不区分场景：
+
+| 模式 | 参数 | 说明 |
+|------|------|------|
+| **异步** | `Async=true`（固定使用） | 不受客户端 60s 超时限制 |
+
+### 为什么是异步？
+
+调用方终端环境（CodeBuddy/WorkBuddy/OpenClaw 等）通常有 **60 秒超时限制**，而 CloudQ 后端 SSE 编排正常耗时在 **5~10 分钟**，长任务最长可达 **20 分钟**。如果使用同步模式，客户端超时会直接断开连接，用户永远得不到结果。
+
+异步模式将"请求"与"结果获取"解耦：
+1. 发起异步请求 → 立即返回 accepted（< 1s，不受超时限制）
+2. 轮询查询结果 → 每次查询 < 1s，间隔可控
+
+**因此所有调用一律使用异步模式。**
+
+## 调用示例
+
+```bash
+# 发起异步请求
+python3 {baseDir}/scripts/tcloud_sse_api.py '列出架构图' --source codebuddy --session-id <uuid>
+
+# accepted 帧返回：
+# {"success":true,"data":{"chat_id":"chat-xxx","session_id":"sess-xxx","content":"任务已受理...","is_accepted":true}}
+
+# 查询任务状态（每次 <1s，不触发终端超时）
+python3 {baseDir}/scripts/tcloud_async_task.py query <chat_id> <session_id>
+
+# 取消任务
+python3 {baseDir}/scripts/tcloud_async_task.py cancel <chat_id> [session_id]
+```
+
+## 参数
+
+| 参数 | 必选 | 类型 | 描述 |
+|------|------|------|------|
+| Question | 是 | String | 用户问题，如 `列出架构图` |
+| SessionID | 是 | String | 会话 ID（UUID v4），同一对话必须保持不变 |
+| Source | 否 | String | 调用来源平台标识（不区分大小写），AI 根据当前运行环境自动判断，可选值：`codebuddy`、`workbuddy`、`openclaw`、`qclaw`、`hermes` 等 |
+| Async | 否 | Boolean | 是否异步模式，默认 true。始终使用异步 |
+| UseCloudQCredential | 否 | Boolean | OAuth 鉴权时自动设为 true，标识使用 CloudQ 控制台凭证 |
+| UIRenderEvent | 否 | Boolean | 是否返回结构化 UI 事件 |
+| Messages | 否 | Array | 历史消息上下文 |
+| Model | 否 | String | 模型名称 |
+
+## 返回格式
+
+### 异步 accepted 帧
+
+```json
+{
+  "success": true,
+  "action": "CloudQChatCompletions",
+  "data": {
+    "session_id": "049bbd09-c5c9-48fa-b9c0-8952d94e53fe",
+    "content": "当前账号下共有 **10 张**架构图...\n\n[前往智能顾问控制台](免密登录URL)",
+    "is_final": true
+  },
+  "requestId": "d72bal4g699bmj4h7gs0"
+}
+```
+
+### 异步模式（accepted 帧）
+
+```json
+{
+  "success": true,
+  "action": "CloudQChatCompletions",
+  "data": {
+    "chat_id": "chat-7f3a9b2e1d4c",
+    "session_id": "sess-e5b8c1a0f6d2",
+    "content": "任务已受理...",
+    "is_accepted": true
+  }
+}
+```
+
+### 异步任务查询结果（DescribeCloudQAsyncTask）
+
+```json
+{
+  "success": true,
+  "action": "DescribeCloudQAsyncTask",
+  "data": {
+    "Status": "completed",
+    "FinishReason": "stop",
+    "Content": "根据您的云架构分析，建议优化以下资源配置...",
+    "SessionID": "sess-e5b8c1a0f6d2",
+    "ChatID": "chat-7f3a9b2e1d4c"
+  }
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `session_id` | String | **会话 ID**（UUID v4），用于标识同一轮对话。多轮对话时必须传入此值以保持上下文 |
+| `content` | String | Markdown 格式回答（控制台链接已自动替换为免密登录链接） |
+| `is_final` | Boolean | 是否为最终结果 |
+| `requestId` | String | 请求追踪 ID（仅用于日志排查，**不能用作会话标识**） |
+
+异步模式额外字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `chat_id` | String | 异步任务 ID，用于后续 `DescribeCloudQAsyncTask` 查询 |
+| `is_accepted` | Boolean | 是否为 accepted 帧（异步模式） |
+
+## FinishReason 枚举
+
+| 值 | 含义 | 出现场景 |
+|----|------|----------|
+| `stop` | 正常完成 | 编排自然结束 |
+| `user_stopped` | 用户主动停止 | `CancelCloudQChat` / `CancelCloudQAsyncTask` 触发 |
+| `timeout` | 执行超时 | 编排超过时间上限自动终止 |
+| `error` | 执行异常 | panic / 系统错误 |
+
+## 脚本自动处理（无需手动干预）
+
+`tcloud_sse_api.py` 在返回 content 前会自动执行以下处理：
+
+1. 扫描 `console.cloud.tencent.com` 链接，替换为免密登录链接
+2. 如果链接不含 archId 但内容中有架构图 ID（`arch-xxx`），自动拼入
+3. 自动追加 `hideTopNav=true` 参数
+4. 已是免密登录链接的不会重复处理
+5. 免密链接生成失败时保留原链接
+6. 如果 content 中没有任何免密链接，自动在末尾追加 `[前往智能顾问控制台](免密登录URL)`
+
+## 展示规则
+
+- `content` **已包含免密登录链接**，可直接展示给用户，无需额外生成
+- 严禁直接展示完整免密登录 URL，必须以 Markdown 超链接格式展示
+
+## 错误返回
+
+调用失败时返回统一错误格式，**必须将错误码和错误信息展示给用户**：
+
+```json
+{
+  "success": false,
+  "action": "CloudQChatCompletions",
+  "error": {
+    "code": "UnauthorizedOperation",
+    "message": "The operator is not authorized."
+  },
+  "requestId": "18b169de-4e4e-46d9-80ff-53053f34b0d7"
+}
+```
+
+## 常见错误码
+
+| 错误码 | 说明 | 处理方式 |
+|--------|------|---------|
+| `AuthFailure.SecretIdNotFound` | SecretId 不存在 | 提示用户检查 AK/SK 配置 |
+| `AuthFailure.SignatureFailure` | 签名验证失败 | 提示用户检查 SecretKey 是否正确 |
+| `AuthFailure.InvalidSecretId` | SecretId 无效 | 提示用户检查 AK/SK 配置 |
+| `UnauthorizedOperation` | 无操作权限 | 提示用户当前账号无权调用此接口，需授权 `QcloudAdvisorFullAccess` 策略 |
+| `UnauthorizedOperation.CamUnauthorized` | CAM 鉴权未通过 | 提示用户为子账号授予智能顾问相关权限 |
+| `FailedOperation` | 操作失败 | 将错误信息原样展示给用户 |
+| `ResourceNotFound` | 资源不存在 | 提示用户可能未开通智能顾问，调用 `DescribeUserAuthorizationStatus` 确认 |
+| `RequestLimitExceeded` | 请求频率超限 | 提示用户稍后重试 |
+| `ErrMissingParameter` | 必填参数缺失 | 检查 ChatID/SessionID 是否传入 |
+| `ErrOperationDenied` | 无权操作 | 跨用户访问被拒绝 |
+
+## 错误处理规则
+
+1. **必须将 `error.code` 和 `error.message` 展示给用户**，不可吞掉错误
+2. 权限类错误（`UnauthorizedOperation`、`AuthFailure.*`）需提示用户检查账号权限或 AK/SK 配置
+3. 未开通类错误需引导用户通过 `DescribeUserAuthorizationStatus` 确认后决定是否开通