@comate/zulu 1.2.1-beta.2 → 1.3.0

package/comate-engine/assets/skills/{smart-commit → auto-commit-comate}/scripts/icafe/farseer.py

@@ -1,6 +1,8 @@
 """Farseer API 客户端"""
 
-import requests
+import json
+import urllib.parse
+import urllib.request
 from typing import Dict, List, Any, Optional
 
 from .client import FARSEER_BASE_URL, DEFAULT_TIMEOUT, ISSUE_TYPE_MAP
@@ -25,14 +27,11 @@ def get_binding_card_types(space_id: int, timeout: int = DEFAULT_TIMEOUT) -> Lis
     """
     logger.info("查询 farseer 可绑定类型: space_id=%s", space_id)
     try:
-        url = f"{FARSEER_BASE_URL}/storyRule/getRule"
-        response = requests.get(
-            url,
-            params={'icafeSpaceId': space_id},
-            timeout=timeout
-        )
-        response.raise_for_status()
-        data = response.json()
+        query_string = urllib.parse.urlencode({'icafeSpaceId': space_id})
+        url = f"{FARSEER_BASE_URL}/storyRule/getRule?{query_string}"
+        req = urllib.request.Request(url)
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
 
         rule_data = data.get('data', {}).get('data', {})
         binding_types = rule_data.get('engineeringBindingTypes', [])

package/comate-engine/assets/skills/{smart-commit → auto-commit-comate}/scripts/icafe/matching.py

@@ -320,10 +320,38 @@ def resolve_space(
             space_prefix = matched_space.get('prefixCode', '')
             space_id_num = matched_space.get('id')
             space_name = matched_space.get('name', '')
+        elif not space_code_map and git_space_ids:
+            # space_code_map 为空（API 无返回），使用 git log 最高频前缀兜底
+            # 此时没有 space_id_num，但 IQL 查询仍可通过 space_prefix 工作
+            space_prefix = git_space_ids[0]
+            logger.warning(
+                "最近访问空间列表为空，使用 git log 最高频前缀兜底: %s",
+                space_prefix,
+            )
+            # 补全 space_code_map，使 available_spaces 和 space_types_map 不为空
+            space_code_map[space_prefix.lower()] = {
+                'prefixCode': space_prefix,
+                'id': None,
+                'name': '',
+            }
 
     if not space_prefix:
-        logger.error("无法自动检测空间")
-        raise ValueError("无法自动检测空间，请通过 space_prefix 参数指定空间前缀")
+        # 收集候选前缀信息，帮助 Agent 快速重试
+        candidates = []
+        try:
+            fallback_ids = git_log_future.result() if not git_space_ids else git_space_ids
+            candidates = fallback_ids[:5] if fallback_ids else []
+        except Exception:
+            pass
+        hint = ""
+        if candidates:
+            hint = f"，git log 中发现的候选前缀: {candidates}"
+        if not space_code_map:
+            hint += "（注意：最近访问空间列表为空，可能是 API 权限问题或用户无最近访问空间）"
+        logger.error("无法自动检测空间%s", hint)
+        raise ValueError(
+            f"无法自动检测空间，请通过 space_prefix 参数指定空间前缀{hint}"
+        )
 
     return space_prefix, space_id_num, space_name, space_code_map
 
@@ -443,30 +471,41 @@ def build_output(
     Returns:
         完整的输出字典
     """
+    # 默认兜底卡片类型
+    _fallback_types = [
+        {"id": "5007", "name": "Story"},
+        {"id": "54444", "name": "Task"},
+        {"id": "5009", "name": "Bug"},
+    ]
+
     # 构建可用空间列表（包含每个空间的卡片类型）
     available_spaces = []
     for s in space_code_map.values():
         prefix = s.get('prefixCode', '')
+        types = space_types_map.get(prefix.lower(), [])
         available_spaces.append({
             "id": s.get('id'),
             "prefix": prefix,
             "name": s.get('name', ''),
-            "types": space_types_map.get(prefix.lower(), [])
+            "types": types if types else _fallback_types
         })
 
     # 构建默认值
     defaults = {
         "title": "",
         "type_id": "",
+        "type_name": "",  # 由 Agent 根据 diff 语义推断，或使用下面的默认值
         "space_id": space_id_num
     }
-    # 从当前匹配空间的 types 中取第一个类型作为默认值
+    # 优先使用 farseer 的绑定类型（更精准，仅含绑定了代码提交流程的类型）
+    # 兜底使用 space_types_map 的全量类型
     current_space_types = space_types_map.get(space_prefix.lower(), []) if space_prefix else []
-    if current_space_types:
-        defaults["type_id"] = current_space_types[0]["id"]
-    elif available_types:
-        # 兜底使用 farseer 的 available_types
+    if available_types:
         defaults["type_id"] = available_types[0]["id"]
+        defaults["type_name"] = available_types[0]["name"]
+    elif current_space_types:
+        defaults["type_id"] = current_space_types[0]["id"]
+        defaults["type_name"] = current_space_types[0]["name"]
 
     output: Dict[str, Any] = {
         "cards": cards,
@@ -586,7 +625,10 @@ def find_matching_card(
             "space_name": "空间名称",
             "final_iql": "...",
             "available_types": [{"id": "5009", "name": "Bug"}, ...],
-            "available_spaces": [{"id": 12345, "prefix": "dkx", "name": "空间名称"}, ...],
+            "available_spaces": [
+                {"id": 12345, "prefix": "dkx", "name": "空间名称",
+                 "types": [{"id": "5009", "name": "Bug"}]}, ...
+            ],
             "defaults": {
                 "title": "",         # 由 Agent 根据 diff 生成
                 "type_id": "5009",   # 默认卡片类型 ID
@@ -634,6 +676,20 @@ def find_matching_card(
 
     # ---- 阶段 3：构建 IQL 并查询卡片 ----
     type_filter, available_types = build_type_filter(space_id_num, include_type_filter)
+
+    # farseer 获取类型失败时（如 space_id_num 为 None），从 space_types_map 兜底
+    if not available_types and space_prefix:
+        available_types = space_types_map.get(space_prefix.lower(), [])
+
+    # 最终兜底：如果仍然为空，使用默认的三种常用卡片类型
+    if not available_types:
+        available_types = [
+            {"id": "5007", "name": "Story"},
+            {"id": "5009", "name": "Bug"},
+            {"id": "54444", "name": "Task"},
+        ]
+        logger.warning("可绑定卡片类型为空，使用默认兜底类型: Story, Bug, Task")
+
     result = build_iql_and_query(client, space_prefix, space_id_num, lookback_days, type_filter, max_records)
     logger.info("IQL 查询完成, 获得 %d 张卡片, iql=%s", len(result["cards"]), result["final_iql"])
 

package/comate-engine/assets/skills/auto-commit-comate/scripts/match_card_cli.py

@@ -0,0 +1,37 @@
+"""命令行工具：查询 iCafe 匹配卡片
+
+用法:
+    python3 match_card_cli.py --username "dongkexin01"
+
+输出:
+    JSON 格式的匹配结果，包含 cards、space_prefix、available_types 等字段。
+    失败时输出 {"error": "错误信息"} 或 {"disabled": true, "message": "..."}。
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from icafe.matching import find_matching_card
+
+
+def main():
+    """解析命令行参数并查询匹配卡片。"""
+    parser = argparse.ArgumentParser(description="查询 iCafe 匹配卡片")
+    parser.add_argument("--username", default=None, help="用户名，如 dongkexin01")
+    args = parser.parse_args()
+
+    try:
+        username = args.username or os.environ.get("COMATE_USERNAME")
+        result = find_matching_card(current_user=username)
+        print(json.dumps(result, ensure_ascii=False))
+    except Exception as e:
+        print(json.dumps({"error": f"查询匹配卡片异常: {type(e).__name__}: {e}"}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/comate-engine/assets/skills/cnap-comate/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: cnap
+description: Deploy, inspect and operate K8s-based applications on CNAP (Cloud-Native Application Platform).
+license: Apache-2.0
+metadata:
+  author: dongshuzhao@baidu.com
+  version: "0.3"
+  enableWhen:
+    - isInternal
+---
+# CNAP 操作技能
+
+CNAP（Cloud-Native Application Platform）是百度内部的云原生应用平台，用于 K8s 应用的 CI/CD。本技能帮助用户通过 CNAP CLI 进行应用部署排查、日志查看、容器操作等值班相关工作。
+
+**核心概念**：
+
+- **账号 (Account)**：用户或团队的业务归属单元，与百度云内部资源账号绑定
+- **环境 (Environment)**：按照环境功能进行的隔离，如 prod、sandbox、test、dev 等环境，又分为生产和测试两个级别
+- **应用 (App)**：具体的业务应用名称，有些用户也把它称作“服务”、“模块”等
+- **集群 (Cluster)**：对应实际的K8s集群在CNAP的名称，通常对应地域+AZ，有些用户也把它称作“机房”等
+
+上述4个基本概念通过组合，实现K8s资源和应用的多维度管理。
+
+- **K8s资源三元组**：namespace为CNAP管理集群资源的单元，每个 <账号, 环境, 集群> 三元组对应一个K8s集群的namespace；一个namespace可部署多个应用。
+- **应用环境三元组**：在应用维度，所有应用以 <账号, 环境, 应用> 三元组定义；一个应用可以部署在若干K8s集群。
+
+CNAP CLI 会自动管理系统kubeconfig，每个用户使用过的环境，会自动建立名为 'cnap:<账号名>-<环境名>:<集群名>' 的context。
+
+## 触发场景
+
+当用户有以下场景时，使用此技能：
+
+- 应用部署失败、启动失败的排查
+- 查看应用/Pod状态、容器日志
+- 登录容器执行命令
+- 批量在多个Pod上执行操作
+- 文件传输（上传/下载）
+- 环境切换、kubeconfig上下文管理
+- 部署管理（查看、发起、控制部署）
+
+**触发关键词**：CNAP, appspace, 一站式, 部署, 部署单, 上线, deploy, Pod, 容器日志, K8s, EKS, WebSSH
+
+## 前置检查：安装与登录
+
+### 检查 CNAP CLI 是否已安装
+
+```bash
+which cnap || echo "NOT_INSTALLED" && cnap version --no-logo
+```
+
+**当前版本要求**：0.7.1及以上。
+
+### 自动安装或升级
+
+```bash
+url="http://bj.bcebos.com/appspace/cnap-cli/install_cnap_cli.sh" && cnap update --latest --quiet || ((curl -s $url || wget $url -q -O -) | sh)
+```
+
+更多安装方式参考 `references/install.md` 。
+
+### 登录
+
+使用以下命令获取登录状态：
+
+```bash
+cnap login status
+```
+
+登录状态无需每次检查。若需要的操作未登录，命令会提示'login required'的错误信息，需要提示用户访问 [https://uuap.baidu.com/agent/token] 获取 UGate Token，并让用户粘贴给Agent，然后Agent执行以下命令：
+
+```bash
+cnap login ugate --token <ugate-token>
+```
+
+## 核心命令速查
+
+**通用要求**：
+1. 大部分命令都支持交互式（无参数）、非交互式（有参数）两种执行方式。请在命令中将参数列全，使用有参数方式one-shot提高效率，避免进入交互式执行等待输入造成阻塞。
+2. 以下速查中，没列举出来的参数，不要自己随便编造参数，以免失败或遇到其他非预期结果，除非你用 `cnap help` 事先确认过。
+
+### 资源查询
+
+- `cnap query url <URL>` - 根据CNAP平台页面URL，查询页面类型和账号、应用、部署ID等参数
+- `cnap query pod <pod_name|pod_ip>` - 根据名称或IP查询用户有权限的 Pod
+- `cnap query app <name|id|repo>` - 根据应用名称（可模糊查询）、应用ID或代码库（iCode）地址，查询应用信息
+
+提示：
+- 当用户输入了一个外部资源（如URL、代码库名、应用名）等，可以用 `query` 系列命令检索内部信息（如账号、环境、应用等），然后再调用相关命令进行处理。
+- CNAP平台URL通常以 `console.cloud.baidu-int.com/devops/appspace` 开头，也可能在 `appspace.baidu-int.com` 域名下
+
+### 环境管理
+
+- `cnap env show` - 查看当前环境上下文（账号/环境/集群）
+- `cnap env switch -A <account> -E <env> -C <cluster>` - 切换环境 **（-A、-E、-C 参数应同时存在）**
+- `cnap env sync [--all]` - 同步当前（或所有）环境上下文的 kubeconfig（通常无需手动执行，仅在远端kubeconfig发生变化时需要重新同步）
+
+注意：以下的命令一般都要求在对应的环境上下文上执行，所以需要先 `env switch` 切换到对应环境，记得-A/-E/-C参数不要缺失
+
+### 资源获取
+
+- `cnap get account` - 获取可访问账号列表
+- `cnap get env [-A <account>]` - 获取当前账号（或指定账号<account>的）环境列表
+- `cnap get app [-C <cluster>]` - 获取当前账号、环境（及指定集群<cluster>）的应用列表
+- `cnap get cluster [-a <app>]` - 获取当前账号、环境（及指定应用<app>）的集群列表
+- `cnap get pod [-a <app>] [-C <cluster>] [--all]` - 获取当前账号、环境、集群（或指定集群<cluster>/所有集群--all、指定应用<app>）的Pod列表
+
+提示：`get` 和 `query` 系列命令支持 `[-o json|yaml]` 参数，必要时使用 `-o json` 格式输出，能够获得更结构化、更全面的信息（但输出也会更长），也可以配合 `jq` 等工具进一步处理。
+
+### 容器操作
+
+- `cnap ssh [pod] [-c <container>] [-r]` - 登录容器（`-r`只读模式）
+- `cnap exec [pod] -- <cmd> [-c <container>] [-r]` - 执行命令
+- `cnap exec [pod] -- sh -c '<cmd>'` - 执行带 Shell 语法的命令
+- `cnap batch --app <app> [-c <container>] [-C <cluster> | --all-cluster] [-p <num>] -y -- <cmd>` - 在指定应用<app>的Pod上批量执行命令（`-p`指定并发度）
+
+### 文件传输
+
+- `cnap cp <pod>:<remote> <local> [-c <container>]` - 下载文件
+- `cnap cp <local> <pod>:<remote> [-c <container>]` - 上传文件
+
+### 部署管理
+
+- `cnap deploy list [--app <app> | --repo-path <repo>] [-o json|yaml]` - 根据应用名或代码库地址获取部署列表
+- `cnap deploy create --repo-path <repo> --commit-id <id> [-a <app>] [-E <env>] [--branch <branch>] [--change-type NEW_COMMIT|GERRIT_CHANGE]` - 使用指定代码库和commit发起部署
+- `cnap deploy get <deployment-id> [-o json|yaml]` - 获取部署详情
+- `cnap deploy abort <deployment-id>` - 终止部署
+- `cnap deploy pause <deployment-id>` - 暂停部署
+- `cnap deploy resume <deployment-id>` - 恢复部署
+- `cnap deploy confirm <deployment-id> <step-id>` - 确认人工步骤
+- `cnap deploy skip-task <deployment-id> <task-id>` - 跳过任务
+- `cnap deploy redo-stage <deployment-id> <stage-id>` - 重做阶段
+- `cnap deploy redo-task <deployment-id> <task-id>` - 重做任务
+
+### 帮助
+
+- `cnap help <command> [<subcommand>]` - 获取命令详细帮助
+
+## 生产环境注意事项
+
+1. **读写分离**：某些生产环境有权限限制，此时普通用户 `cnap ssh` 只能以只读模式登录容器或者无法登录
+2. **谨慎操作**：批量操作 `batch` 会影响多个 Pod，务必先用 `--dry` 参数确认执行计划
+3. **风险命令**：除非用户强要求，原则上不允许 Agent 执行 `rm`、`kill` 等破坏性命令
+
+## 其他信息
+
+### 与 kubectl 配合使用
+
+通过 `cnap env switch` 系列命令切换context，它会管理 ~/.kube/config ，之后可以与 `kubectl` 正常交互，详见 `references/kubectl.md` 。
+
+### 值班表
+
+包括CNAP平台及相关的EKS、iPipe、iRegistry、iCode等平台，详见 `references/oncall.md` 。
+
+### 典型案例
+
+- 部署单排障的流程，详见 `references/deploy-troubleshoot.md` 。
+- 查看日志、排查问题、文件传输等，详见 `references/cases.md` 。

package/comate-engine/assets/skills/cnap-comate/references/cases.md

@@ -0,0 +1,198 @@
+# CNAP CLI 使用案例
+
+本文件包含 CNAP CLI 的典型使用场景和示例命令。
+
+## 场景零：快速了解资源和环境
+
+```bash
+# 查看可访问的账号列表
+cnap get account
+
+# 查看当前账号下的环境列表
+cnap get env
+
+# 查看指定账号下的环境列表
+cnap get env -A inf
+
+# 查看当前环境下的集群列表
+cnap get cluster
+
+# 以 JSON 格式输出（便于脚本处理）
+cnap get app -o json
+cnap get pod -a my-app -o yaml
+```
+
+## 场景一：应用部署失败排查
+
+**排查步骤：**
+
+```bash
+# 1. 确认当前上下文所在环境
+cnap env show
+
+# 2. 切换到目标环境（如需要）
+cnap switch --env <env> --cluster <cluster>
+
+# 3. 查看应用状态
+cnap get app -w <app> -o wide
+
+# 4. 查看 Pod 状态
+cnap get pod -a <app> -o wide
+
+# 5. （配合kubectl）查看 Pod 详情（定位 Pending/ImagePullBackOff 等问题）
+kubectl describe pod <pod>
+
+# 6. （配合kubectl）查看事件
+kubectl get events --sort-by='.lastTimestamp' | head -20
+```
+
+## 场景二：查看容器日志
+
+```bash
+# 方式一：exec 查看单Pod日志文件
+cnap exec <pod> -- tail -100 /app/logs/error.log
+cnap exec <pod> -- sh -c 'cat /app/logs/*.log | grep ERROR'
+
+# 方式二：批量查看多Pod日志
+cnap batch --app <app> -- sh -c 'tail -50 /app/logs/error.log'
+```
+
+## 场景三：检查配置和进程
+
+```bash
+# 查看容器内配置
+cnap exec <pod> -- cat /etc/config/app.yaml
+cnap exec <pod> -- env | grep -i db
+
+# 查看进程状态
+cnap exec <pod> -- ps aux
+
+# 检查网络连通性
+cnap exec <pod> -- curl -v http://backend-service:8080/health
+cnap exec <pod> -- nc -zv mysql-service 3306
+```
+
+## 场景四：批量排查问题
+
+```bash
+# 检查所有 Pod 的配置文件
+cnap batch --app <app> --all-cluster -- cat /app/config/app.yaml
+
+# 批量查找错误日志
+cnap batch --app <app> -- sh -c 'grep ERROR /app/logs/*.log | tail -20'
+
+# 批量检查进程
+cnap batch --app <app> -- ps aux | grep java
+
+# 实时监控多 Pod 日志
+cnap batch --app <app> -p 100 -o realtime --output-options colorful --confirm -- tail -f /app/logs/service.log
+```
+
+## 场景五：文件传输
+
+```bash
+# 下载日志到本地分析
+cnap cp <pod>:/app/logs/service.log ./service.log
+
+# 下载整个日志目录
+cnap cp <pod>:/app/logs ./logs/
+
+# 上传诊断工具
+cnap cp ./debug-tool.sh <pod>:/tmp/
+```
+
+## 场景六：通过 URL 快速定位资源
+
+当从他人分享的 CNAP 控制台 URL 或告警链接中定位问题时：
+
+```bash
+# 解析 CNAP 控制台 URL，获取账号、环境、应用信息
+cnap query url "https://console.cloud.baidu-int.com/devops/appspace/account/860/application/list"
+
+# 解析具体应用页面
+cnap query url "https://console.cloud.baidu-int.com/devops/appspace/account/860/application/123456/runtime/workload"
+
+# 根据 query url 的输出结果切换到对应环境
+cnap switch --account <account> --env <env> --cluster <cluster>
+
+# 继续排查
+cnap get pod -a <app>
+cnap ssh <pod>
+```
+
+## 场景七：跨环境/集群定位 Pod
+
+当只知道 Pod 名称或 IP，但不确定其在哪个环境/集群时：
+
+```bash
+# 根据 Pod 名称查询（跨所有账号环境）
+cnap query pod my-app-5cf65f675f-w5bck
+
+# 根据 Pod IP 查询
+cnap query pod 10.0.0.1
+
+# 输出包含账号、环境、集群、应用、Namespace 等完整信息
+# 然后根据查询结果切换到对应环境继续操作
+cnap switch --account <account> --env <env> --cluster <cluster>
+cnap ssh <pod>
+```
+
+## 场景八：部署管理
+
+### 查看部署列表
+
+```bash
+# 获取当前环境下的部署列表
+cnap deploy list --app myapp
+
+# 根据仓库路径查询
+cnap deploy list --repo-path=baidu/repo/path
+
+# JSON 格式输出
+cnap deploy list --app myapp -o json
+```
+
+### 发起新部署
+
+```bash
+# 使用 commit ID 部署
+cnap deploy create --app myapp --repo-path=baidu/repo/path --commit-id=0123456789abcdefedcba9876543210
+
+# 使用 Gerrit Change 部署
+cnap deploy create --app myapp --repo-path=baidu/repo/path --change-type=GERRIT_CHANGE --commit-id=xxx
+```
+
+### 查看部署详情
+
+```bash
+# 查看部署详情（包括阶段和任务）
+cnap deploy get <deployment-id>
+
+# JSON 格式输出
+cnap deploy get <deployment-id> -o json
+```
+
+### 控制部署
+
+```bash
+# 终止正在进行的部署
+cnap deploy abort <deployment-id>
+
+# 暂停部署
+cnap deploy pause <deployment-id>
+
+# 恢复暂停的部署
+cnap deploy resume <deployment-id>
+
+# 确认人工确认步骤
+cnap deploy confirm <deployment-id> <step-id>
+
+# 跳过失败的任务
+cnap deploy skip-task <deployment-id> <task-id>
+
+# 重做阶段
+cnap deploy redo-stage <deployment-id> <stage-id>
+
+# 重做任务
+cnap deploy redo-task <deployment-id> <task-id>
+```

package/comate-engine/assets/skills/cnap-comate/references/deploy-troubleshoot.md

@@ -0,0 +1,15 @@
+# 使用 CNAP CLI 对部署单进行排障
+
+**应用场景**：用户给了一个部署单地址URL（通常为 `console.cloud.baidu-int.com/devops/appspace` 路径下，并且路径中包含'deploy'字样），并提出了相关问题。
+
+## 典型解决思路
+
+1. 使用 `cnap query url` 命令，通过用户给定的URL，获取到其对应的账号、环境、应用、部署单ID。
+2. 使用 `cnap deploy get <部署单ID> -o json` 命令，获取部署单详情。
+3. 找到有问题的步骤对应的stage和task，根据信息中带'log'的字段，获取其log文件地址。
+4. 访问log地址，获取log文件并阅读，确认可能的问题点，特别要确认有问题的集群名。
+5. 使用 `cnap env switch -A <账号> -C <集群名> -E <环境>` 切换到对应的环境上下文。
+6. 根据上面分析到的问题，可选通过 `cnap exec` 去容器中执行命令，或者借助 `kubectl` 命令，进一步排查确认问题原因。
+7. 给用户简要地解释原因，并给出解决方案。
+   - 如果是偶发问题期望可通过重试解决的，向用户确认是否重试，得到肯定回答后可通过 `cnap depoly redo-stage <deployment-id> <stage-id>` 或 `cnap depoly redo-task <deployment-id> <task-id>` 进行重试。
+   - 如果是外部平台的问题，可以引导通过 `zhiban-search` Skill，查询对应平台的值班表，提示用户找相关人员，相关平台值班信息，详见 `references/oncall.md`。

package/comate-engine/assets/skills/cnap-comate/references/install.md

@@ -0,0 +1,43 @@
+# CNAP CLI 安装与更新
+
+## 安装 CNAP CLI
+
+### 方式一：一行命令安装或更新
+
+此命令会尝试更新 CNAP CLI，如果未安装，则默认安装至 `${HOME}/.cnap/bin/cnap`。
+建议将 `${HOME}/.cnap/bin` 添加到 `PATH` 中以方便后续使用。
+
+```bash
+url="http://bj.bcebos.com/appspace/cnap-cli/install_cnap_cli.sh" && cnap update -q || ((curl -s $url || wget $url -q -O -) | sh)
+```
+
+### 方式二：使用系统包管理器
+
+前提：系统上已经安装了百度内部软件源（地址前缀为 `bj.bcebos.com/baidu-packages`），需要有 root 或 sudo。
+
+```bash
+# Ubuntu
+apt-get install -y cnap
+
+# Alpine
+apk add cnap
+
+# CentOS
+yum install cnap -y
+```
+
+### 检查安装状态
+
+```bash
+which cnap || echo "NOT_INSTALLED" && cnap version --no-logo
+```
+
+## 更新 CNAP CLI
+
+```bash
+cnap update --latest --quiet
+```
+
+## 登录认证
+
+登录认证详细说明请参考 [auth.md](./auth.md)。

package/comate-engine/assets/skills/cnap-comate/references/kubectl.md

@@ -0,0 +1,55 @@
+# CNAP CLI 与 kubectl 配合使用
+
+## kubeconfig 位置
+
+CNAP CLI 与 kubectl 完全兼容，kubeconfig 存储在 `~/.kube/config`。
+
+## 使用流程
+
+1. 使用 `cnap switch` 切换环境（更新 kubeconfig context）
+2. 使用 `kubectl` 执行更多操作
+
+## 概念对照
+
+### 集群与 Namespace
+
+每个环境可对应若干个 K8s 集群。在每个集群上，应用部署在名称为 `<account>-<environment>` 的 namespace 中。
+
+### kubeconfig 上下文
+
+集群+namespace 是对 K8s 集群操作的基本单元。在 kubeconfig 中对应 `cnap:<account>-<environment>:<cluster>` 的 context。
+
+## 环境切换
+
+在对每个应用的 K8s 资源进行操作前，需要使用 `cnap env` 系列命令切换环境。具体命令请参考 SKILL.md 中的核心命令速查部分。
+
+## 常用组合
+
+```bash
+# 1. 使用 cnap 切换环境
+cnap switch --account appspace-test --env sandbox --cluster nb-bjdd
+
+# 2. 然后用 kubectl 执行更多操作
+kubectl get pods -o wide
+kubectl logs <pod> --tail=100
+kubectl describe pod <pod>
+kubectl get events --sort-by='.lastTimestamp'
+
+# 3. 查看特定 Pod 的详细状态
+kubectl get pod <pod> -o yaml
+
+# 4. 查看资源限制和配置
+kubectl get pod <pod> -o jsonpath='{.spec.containers[*].resources}'
+
+# 5. 查看节点信息
+kubectl get nodes
+
+# 6. 查看 namespace 下的所有资源
+kubectl api-resources --namespaced=true
+```
+
+## 注意事项
+
+- CNAP CLI 自动管理 kubeconfig 中的 context，无需手动配置
+- 切换环境后，kubectl 会自动使用新的 context
+- 使用 `cnap env show` 查看当前使用的 context