xxiaoxiong/dsh-kubernetes

dsh-kubernetes 为 DeepSeek Harness 提供安全的 Kubernetes 能力：检查工作负载、获取有界日志与事件、诊断常见故障，并在审批后执行受控变更。

DeepSeek Harness (DSH) 社区插件。它不是 kubectl 包装器 —— 而是把 Kubernetes 变成结构化、对 Agent 友好的运行时能力，并内置 Read-first 安全模型。

DSH Agent
   ↓
通用 Kubernetes Tools（10 个）
   ↓
ctx.kubernetes 能力服务
   ↓
KubernetesService（策略 · 诊断 · 边界控制）
   ↓
KubernetesClientProvider（@kubernetes/client-node）
   ↓
Kubernetes API

核心特性

• 默认只读 —— 开箱即 readOnly: true。真实写操作需要显式开启并且通过 DSH 审批门。
• 10 个结构化工具 —— 每个工具都返回带 schema 的 JSON 和紧凑文本渲染；不解析脆弱的 CLI 输出。
• k8s_diagnose 证据引擎 —— 沿 Deployment/StatefulSet → Pod → 容器 → 事件 → 有界日志逐层收集并归类常见故障（CrashLoopBackOff、ImagePullBackOff、OOMKilled、探针失败等）。插件内部不调用第二个 LLM：插件负责收集证据，DSH Agent 负责推理。
• 有界、脱敏日志 —— 支持 tailLines / sinceSeconds / container / previous / maxChars，并施加硬上限。日志被视为不可信数据：密钥形状的值被脱敏，ANSI/控制字符被清除。
• Secret 永不泄露 —— k8s_describe secret 只返回 metadata、type 和 data 键名。凭据形状字段（token、password、client-key-data、ServiceAccount token、容器 env 中的密钥等）在全链路脱敏。
• 受控的 k8s_apply —— 默认服务端 dry-run；真实 apply 在只读策略下直接拒绝，开启写权限后升级为审批（ask），审批理由中包含集群/命名空间上下文与生产环境风险提示。

安装

dsh plugin add dsh-kubernetes          # 从 npm 安装（发布后）
# 或从打包产物安装：
npm pack
dsh plugin add ./dsh-kubernetes-0.1.0.tgz

也支持在 DSH 之外作为普通库使用 —— 包导出宿主无关 API：

import { KubernetesClientProvider, DiagnosisEngine, KubernetesService } from 'dsh-kubernetes';

配置

kubeconfig 解析遵循标准优先级：显式 kubeconfigPath → KUBECONFIG 环境变量 → ~/.kube/config → 集群内 ServiceAccount。绝不静默切换 context。

选项	默认值	说明
readOnly	true	只读模式。即使 allowWrite 为 true 也禁止真实写入。
allowWrite	false	写操作总开关。真实 apply 还需通过审批。
context	–	显式 kubeconfig context 覆盖。
namespace	context 命名空间 / default	默认命名空间覆盖。
kubeconfigPath	–	显式 kubeconfig 文件路径。
maxLogChars	8000	每段日志的字符硬上限（500–20000）。
maxLogTailLines	200	每次日志请求的尾部行数硬上限（1–500）。
maxLogSinceSeconds	3600	日志时间窗硬上限（秒，10–21600）。

Profile 示例 —— 插件包内的 cordis.patch.yml 会自动以 insert 方式挂载本插件并附带安全默认值；如需在你的 profile 层覆盖配置，按 id 覆盖即可：

- id: dsh-kubernetes
  config:
    readOnly: true
    allowWrite: false

工具列表

工具	权限	作用
k8s_context	读	当前 context、集群 server、生效命名空间、能力集、全部 context（不含凭据）。
k8s_namespaces	读	命名空间及状态。
k8s_workloads	读	Deployment/StatefulSet/DaemonSet 副本数与健康度，不健康优先排序。
k8s_pods	读	Pod 阶段、健康度、重启次数、容器等待原因（上限 200 条）。
k8s_describe	读	脱敏后的资源描述。Secret 只返回 metadata/type/键名。
k8s_logs	读	有界、脱敏、去重的 Pod 日志。
k8s_events	读	事件（可按资源过滤），脱敏且有界。
k8s_diagnose	读	结构化 DiagnosisEvidence 与可能故障类别。
k8s_rollout	读	工作负载滚动状态。
k8s_apply	门控	默认服务端 dry-run；真实 apply 需 allowWrite 且审批。

安全模型

readOnly=true（默认）         readOnly=false + allowWrite=true
────────────────────────     ─────────────────────────────────
get/list/describe  ✓         get/list/describe          ✓
logs/events        ✓         logs/events                ✓
apply dryRun=true  ✓         apply dryRun=true          ✓
apply dryRun=false ✗ 拒绝    apply dryRun=false         → 审批（ask）

• 写操作显式绑定 context / cluster / namespace / resource，审批前完整展示。
• context 名称含 prod/production/prd 时提高审批理由中的风险级别（字符串匹配只是提示，绝不作为安全依据）。
• v1 刻意不提供 delete、exec、port-forward、scale、restart、rollback 工具。
• kubeconfig 内容、token、client key、证书绝不进入工具结果或会话。

故障诊断 Demo

用户：为什么 production/order-service 一直重启？

Agent → k8s_diagnose(Deployment/order-service)

Evidence:
- deployment: 期望 3 / 就绪 1 — progressing
- pods: 共 3 个；2× CrashLoopBackOff（unhealthy）
- containers: 上次终止 OOMKilled（exit 137），重启 14 次
- 内存 limit: 所有容器 512Mi
- 相关事件: BackOff ×14（Warning）
- 有界日志（tail 40，已脱敏）: "OOMkilled while serving traffic"
- likelyCategories: ["crash-loop", "oom-killed"]

插件将类别标记为可能而非确定事实 —— 最终推理由 DSH Agent 完成。

Dry-run / 审批 Demo

Agent → k8s_apply(manifest, dryRun=true)
结果: applied (server-side dry-run): ConfigMap/order-service-config (namespace default)

用户：没问题，正式应用吧

Agent → k8s_apply(manifest, dryRun=false)
审批请求（ask）:
  k8s_apply with dryRun=false targets context "kind-dsh-e2e" (namespace "default").
  Approve to perform the real change.

默认只读策略下，同样的调用会被直接拒绝：

{ kind: "deny", reason: "real apply denied: plugin is read-only (readOnly=true, allowWrite=false). Set allowWrite=true and readOnly=false to enable approval-gated writes." }

兼容性

组件	测试版本
DeepSeek Harness 插件 API	@deepseek-ai/dsh-tools 0.1.0-rc.6
Cordis 运行时	@deepseek-ai/cordis 4.0.1
Kubernetes 客户端	@kubernetes/client-node 1.4.0
Kubernetes 集群	kind v1.32.2（E2E），标准 API 组 core/v1、apps/v1
Node.js	≥ 18.18（在 22.x 上测试）

已知限制

• v1 仅面向标准 Kubernetes（OpenShift / EKS/GKE/AKS 专有认证流程未测试；标准 kubeconfig 可用）。
• k8s_apply 通过服务端 apply 执行 create/update；没有 delete、exec、port-forward、scale/rollback 工具。
• 滚动状态仅支持 Deployment/StatefulSet/DaemonSet；其他类型返回 unknown。
• 日志脱敏基于模式启发式 —— 不保证穷尽所有密钥形态。
• k8s_workloads 不列 CRD（仅核心工作负载类型）；k8s_describe 支持任意类型。

卸载

dsh plugin remove dsh-kubernetes

所有服务/工具注册都挂在插件 fiber 上 —— 移除后全部回滚，无残留监听器或进程。

开发

npm install
npm run lint        # tsc --noEmit
npm test            # 105 个单元 + Mock API + 契约 + cordis 测试
npm run build

# 真实集群 E2E（仅限一次性测试集群）：
kind create cluster --name dsh-e2e
DSH_K8S_E2E=1 npm run test:e2e

许可证

MIT