DSH Deployer — Witty-Builtin-Agents + DeepSeek Harness 部署技能
概述
本技能用于在 openEuler Linux 服务器上一键部署 Witty-Builtin-Agents + DeepSeek Harness (dsh)。部署完成后，可通过 Headless 命令行或 Web UI（默认 http://127.0.0.1:3080）使用面向 openEuler 的智能运维智能体。
部署原理：dsh 支持 --patch 方式加载 Cordis Overlay 配置，将 witty-builtin-agent 的人设提示词、默认模型（DeepSeek）与 openEuler Portal MCP 注入 dsh 运行时，从而在通用 Agent Harness 上获得面向 openEuler 的系统运维智能体能力。
部署目标环境：openEuler Linux（x86_64 或 aarch64），需 root/sudo 权限，需能访问外网（Node.js、npm、GitHub、AtomGit、SkillHub）。
部署前置检查
在执行部署前，必须先完成以下检查：
- 确认操作系统架构：
uname -m
-x86_64→ Node 架构用x64
-aarch64→ Node 架构用arm64 - 确认有 sudo/root 权限：
sudo -n true - 确认目标目录
/opt/witty-dsh不存在或为空，若存在则提示用户是否覆盖 - 确认 DeepSeek API Key 已准备：需要用户提供有效的
sk-xxxKey - 确认端口 3080 未被占用：
ss -tlnp | grep 3080，若有占用先停止相关进程
部署步骤（9 步）
步骤 1：安装 Node.js v24.19.0
Node.js 版本必须为 v24.19.0，不要使用系统包管理器自带的旧版本。
# 根据架构选择
NODE_ARCH=x64 # x86_64 机器
# NODE_ARCH=arm64 # aarch64 机器
NODE_VERSION=v24.19.0
curl -fsSL "https://nodejs.org/dist/${NODE_VERSION}/node-${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz" -o /tmp/node.tar.xz
sudo mkdir -p /opt/nodejs
sudo tar -xJf /tmp/node.tar.xz -C /opt/nodejs --strip-components=1
echo 'export PATH=/opt/nodejs/bin:$PATH' | sudo tee /etc/profile.d/nodejs.sh
export PATH=/opt/nodejs/bin:$PATH
node -v # 应输出 v24.19.0
npm -v
步骤 2：安装系统依赖与 NPM 包
sudo dnf install -y git curl unzip tar bubblewrap
sudo npm install -g @deepseek-ai/dsh
sudo npm install -g openeuler-portal-mcp
dsh --version # 验证 dsh 可用
步骤 3：拉取 euler-copilot-shell 代码，初始化目录
sudo mkdir -p /opt/witty-dsh && cd /opt/witty-dsh
sudo git clone --depth 1 --branch feat/witty-cli https://atomgit.com/openeuler/euler-copilot-shell.git
sudo mkdir -p builtin-agents
sudo cp -rf euler-copilot-shell/packaging/builtin-agents/. builtin-agents/
# 确认关键文件存在
ls builtin-agents/agents/witty-builtin-agent/witty-builtin-agent.md
ls builtin-agents/config.d/witty-builtin-agent.json
ls builtin-agents/skill-versions.sh
步骤 4：创建 witty.cordis.yml Overlay 配置
文件路径：/opt/witty-dsh/witty.cordis.yml
sudo tee /opt/witty-dsh/witty.cordis.yml > /dev/null <<'EOF'
# Witty Builtin Agent overlay for DeepSeek Harness
- id: system-prompt
config:
persona: !!js "process.getBuiltinModule('node:fs').readFileSync(
'/opt/witty-dsh/builtin-agents/agents/witty-builtin-agent/witty-builtin-agent.md','utf8')"
- id: agent-default-model
config: { provider: deepseek-official, model: deepseek-v4-pro }
- id: llm-deepseek
config:
thinking: enabled
reasoningEffort: max
models: [{ id: deepseek-v4-pro, contextWindow: 128000 },
{ id: deepseek-v4-flash, contextWindow: 128000 }]
- insert:
- id: mcp-openeuler-portal
name: '@deepseek-ai/dsh-mcp-client'
# npm 安装方式（步骤 2 使用 npm install -g）：
config: { serverName: openeuler_portal, transport: stdio,
command: npx, args: ['-y', 'openeuler-portal-mcp'],
failOnStartupError: false, toolCallTimeoutMs: 60000 }
# RPM 包安装方式：
# config: { serverName: openeuler_portal, transport: stdio,
# command: /usr/local/bin/openeuler-portal-mcp,
# failOnStartupError: false, toolCallTimeoutMs: 60000 }
EOF
> ⚠️ persona 层序提示：此补丁写的是部署层 persona，会被 standard 预设自带的 persona 行遮蔽（现象：模型/MCP 生效但人设未变）。排查与修复见 references/common-issues.md。
步骤 5：设置 DeepSeek API Key 凭证
重要：凭证文件权限必须严格为 600，否则 dsh 拒绝加载。将 sk-你的Key 替换为用户提供的真实密钥。
mkdir -p ~/.dsh
printf 'DEEPSEEK_API_KEY: %s\n' 'sk-你的Key' > ~/.dsh/.credentials.yaml
chmod 700 ~/.dsh
chmod 600 ~/.dsh/.credentials.yaml
# 验证权限
ls -la ~/.dsh/.credentials.yaml # 应为 -rw-------
步骤 6（可选）：安装 Skills
第一步：交互式询问。向用户展示以下 6 个可选 Skill 并询问安装哪些，默认推荐 all 全装：
| 编号 | Skill | 版本 | 用途 |
|---|---|---|---|
| 1 | manpage-skill | 1.0.0 | Linux 命令手册查询与分析 |
| 2 | log-anomaly-detector | 1.0.0 | 日志异常模式检测与建议 |
| 3 | html-report-generator | 1.0.0 | HTML 可视化报告生成 |
| 4 | brainstorm-beagle | 1.0.5 | 模糊需求 → 项目规格梳理 |
| 5 | plantuml-skill | 1.4.1 | PlantUML 图表生成 |
| 6 | experience-skill | 1.0.0 | 本地经验库网关（skill_hub/wiki_hub） |
> 版本号以 builtin-agents/skill-versions.sh 为准（单一事实来源）。
询问示例：
请问需要安装哪些 Skills？
- 输入编号安装部分（如 1,3,6）
- 输入 all 安装全部 6 个（推荐）
- 输入 none 跳过本步骤（后续可通过 dsh 内命令补装）
第二步：按用户选择安装。选中的 Skill 统一从 SkillHub 下载：
mkdir -p ~/.dsh/skills
mkdir -p /opt/witty-dsh/skill-dl && cd /opt/witty-dsh/skill-dl
# SELECTED 替换为用户选中的 slug（空格分隔）
SELECTED="manpage-skill log-anomaly-detector html-report-generator brainstorm-beagle plantuml-skill experience-skill"
for slug in $SELECTED; do
echo "Downloading $slug ..."
curl -sSL -H "Referer: https://skillhub.cn/" \
"https://api.skillhub.cn/api/v1/download?slug=${slug}" -o "${slug}.zip"
mkdir -p ~/.dsh/skills/${slug}
unzip -oq "${slug}.zip" -d ~/.dsh/skills/${slug}
done
> 💡 若选中 experience-skill：SkillHub 包不含预编译中文分词扩展与虚拟环境，解压后需在其 scripts/ 目录执行 uv sync（需 Python 3.11+）生成运行环境，随后验证才会通过。
第三步：验证安装结果。对用户选中的每个 Skill 逐一检查，有任一 ❌ 即向用户报告该 Skill 安装失败：
# 检查 SKILL.md 存在且 frontmatter 含 name/description
# （dsh 会静默忽略缺失这些元数据的技能——见 references/common-issues.md §2）
for slug in <用户选中的全部 slug 空格分隔>; do
f="$HOME/.dsh/skills/${slug}/SKILL.md"
if [ -f "$f" ] && head -10 "$f" | grep -q "^name:" && head -10 "$f" | grep -q "^description:"; then
echo "✅ ${slug} 安装成功"
else
echo "❌ ${slug} 缺失 SKILL.md 或 frontmatter 不完整"
fi
done
ls ~/.dsh/skills/
- 若安装了 experience-skill，额外验证 CLI 可用（dsh 沙箱下用 venv 直跑，勿用
uv run）：
cd ~/.dsh/skills/experience-skill/scripts && .venv/bin/experience-skill list-experiences --page 1 --page-size 1
预期：选中的每个 Skill 输出 ✅；experience-skill 的 CLI 正常返回（空库也算正常）。
步骤 7：Headless 命令行交互测试
cd /opt/witty-dsh
dsh --profile headless --patch /opt/witty-dsh/witty.cordis.yml "你好，请介绍一下你自己"
预期：返回以 Witty Assistant 身份的中文自我介绍，说明是 openEuler 运维助手。若报错，根据错误信息排查（常见原因：API Key 错误、网络不通、Node 版本不对）。
步骤 8：后台启动 Web 服务
cd /opt/witty-dsh
nohup dsh web --patch /opt/witty-dsh/witty.cordis.yml > /opt/witty-dsh/web.log 2>&1 &
echo $! > /opt/witty-dsh/web.pid
# 等待 5-10 秒后检查
sleep 8
ss -tlnp | grep 3080
tail -20 /opt/witty-dsh/web.log
预期：端口 3080 处于 LISTEN 状态，日志无致命错误。
停止 Web 服务：
kill $(cat /opt/witty-dsh/web.pid) 2>/dev/null
pkill -f "dsh web"
步骤 9：SSH 本地端口转发访问 WebUI
在用户本地机器（非服务器）执行：
ssh -L 3080:127.0.0.1:3080 <用户名>@<服务器地址>
然后在本地浏览器打开：http://127.0.0.1:3080
部署后验证清单
部署完成后逐项确认：
| 检查项 | 命令 | 预期 |
|---|---|---|
| Node 版本 | node -v |
v24.19.0 |
| dsh 可用 | dsh --version |
输出版本号 |
| 凭证权限 | ls -la ~/.dsh/.credentials.yaml |
-rw------- |
| Overlay 文件 | ls /opt/witty-dsh/witty.cordis.yml |
文件存在 |
| Agent 提示词 | ls /opt/witty-dsh/builtin-agents/agents/witty-builtin-agent/witty-builtin-agent.md |
文件存在 |
| Portal MCP 包 | npm list -g openeuler-portal-mcp |
全局已安装 |
| Web 端口 | ss -tlnp \| grep 3080 |
LISTEN 状态 |
| Headless 测试 | dsh --profile headless --patch /opt/witty-dsh/witty.cordis.yml "你好" |
正常返回中文回答 |
常见问题排查与 FAQ
部署期与运行期的所有高频问题统一收编在 references/common-issues.md，SKILL.md 只保留此索引：
- 常见问题排查（部署期）：EADDRINUSE 3080、凭证权限、MCP 连接失败、Node 版本、npm 安装慢、Web 界面无法访问
- 常见问题（FAQ，运行期）：persona 不生效、技能不显示、沙箱写入受限、配置生效方式、验证速查
注意事项
- 日志位置：Web 服务日志写入
/opt/witty-dsh/web.log，排查异常时首先查看该文件 - 密钥安全：
~/.dsh/.credentials.yaml包含 API Key，不要提交到版本控制或泄露 - Overlay 配置修改：修改
witty.cordis.yml后需重启 dsh 服务生效 - 多用户部署：每个用户的
~/.dsh/目录独立，API Key 与 Skills 按用户隔离；若需全局共享 Skills，可放到/usr/share/witty/等公共目录并在配置中引用 - Skills 可选：步骤 6 的 6 个 Skill 为增强能力，未安装时基础问答仍可工作，但日志分析、HTML 报告、绘图、本地经验检索等能力不可用
- Windows 本地开发：本技能面向 openEuler Linux 目标服务器，若用户在 Windows 本地直接部署 dsh，注意路径分隔符与
.dsh目录位置差异（Windows 下为%USERPROFILE%\.dsh），且 bubblewrap 在 Windows 不可用需跳过
一键部署脚本参考（可选提供）
若用户需要一键部署，可将以上步骤封装为 bash 脚本。脚本需接收参数：--api-key=<sk-xxx>、--arch=<x64|arm64>、--with-skills（是否安装 Skills）、--start-web（是否启动 Web）。
脚本执行流程：前置检查 → 步骤 1-6 → （可选）步骤 7 测试 → （可选）步骤 8 启动 → 输出访问指引。
