---
name: sophnet-qa-install
description: 创建或更新智能客服系统（知识管理员 + 问答助手），包括工作空间初始化、模板下载、角色配置和配置文件注入。当用户要求创建客服系统、更新客服系统、智能问答、知识库客服时使用。
version: 1.0.3
---

# 智能客服系统创建与更新

创建或更新包含「知识管理员」和「问答助手」两个 Agent 的智能客服系统。创建和更新共用同一套流程（Step 2～6），区别仅在于：新安装需收集参数（Step 1），更新则复用已有配置并需用户确认。

## Processing Mode

**STRICT SERIAL PROCESSING ONLY** — 按顺序逐步执行，不要拆分子任务或并行处理。

## Prerequisites

- Python 3.10+
- unzip

## 流程

### Step 0: 校验安装状态

执行校验脚本，根据返回状态决定后续流程。`{version}` 取自本文件 frontmatter 中的 `version` 字段：

```bash
uv run {baseDir}/scripts/check_installed.py --version {version}
```

脚本输出三种状态：

#### 退出码 0 — `INSTALLED`（已安装，无需操作）

向用户展示以下提示，并**终止流程**（不再执行 Step 1～6）。其中「客服子系统的API Secret」从 `openclaw.json` 的 `channels.bot-api.accounts["qa-agent"].apiSecret` 读取（与 `scripts/update_config.py` 中 `get_api_secret` 一致）。

```
智能客服系统已经安装，无需重复安装。

📂 知识库目录：/home/node/.openclaw/workspace-knowledge/knowledge
🤖 管理员会话：knowledge-admin
💁 客服助手会话：qa-agent
🔑 客服子系统的API Secret: <api_secret>

📝 常用命令（在 knowledge-admin 会话中使用）：
  • 通过附件按钮上传文件，并输入：将文档加入知识库
  • 将 https://xxx 中的内容加入到知识库
  • 将 xxx 写入到知识库
  • 昨天客户都问了哪些问题
  • 昨天客户都有哪些反馈
  • 删除 xxx 知识库
```

#### 退出码 2 — `UPDATABLE`（可更新）

文件已存在但版本低于目标版本，有新版本可用。脚本会额外输出已有配置中的 `ADMIN_NAME` 和 `QA_NAME`（如 `ADMIN_NAME=客服管理员`、`QA_NAME=客服助手`）。

**必须先向用户确认，禁止直接更新。** 向用户展示以下提示并等待回复。其中 `{current_version}` 从 `check_installed.py` 输出或 `workspace-knowledge/git_version` 文件获取：

```
智能客服系统检测到新版本可用（{current_version} → {version}）。

⚠️ 更新说明：
  • 更新不会修改知识库内容
  • 更新会重置 Agent 设置（角色配置等将恢复为模板默认值）
  • 更新前会自动备份当前 Agent 配置到 backup_v{current_version} 目录

是否确认更新？请回复「确认更新」或「取消」。
```

- 若用户回复确认（如"确认更新"、"确认"、"更新"、"好的"、"是"等肯定回复）：先执行配置备份，再**跳过 Step 1**，使用脚本输出的 `admin_name` 和 `qa_name`，从 Step 2 开始执行更新流程。
- 若用户回复取消或其他非肯定回复：**终止流程**，不执行任何更新操作。

##### 备份配置（用户确认后、Step 2 前执行）

依次备份主工作空间和 workspace-qa 目录下的 `.md` 配置文件：

```bash
uv run {baseDir}/scripts/backup_md.py \
  --current-version {current_version} \
  --dir /home/node/.openclaw/workspace-knowledge
```

```bash
uv run {baseDir}/scripts/backup_md.py \
  --current-version {current_version} \
  --dir /home/node/.openclaw/workspace-knowledge/workspace-qa
```

脚本成功后会输出备份目录路径（如 `备份成功: /home/node/.openclaw/workspace-knowledge/backup_v1.0.1`）。向用户展示备份结果：

```
✅ 当前 Agent 配置已备份到：
  • {backup_dir_1}
正在开始更新...
```

备份完成后，继续执行 Step 2～6。

#### 退出码 1 — `NOT_INSTALLED`（未安装）

未安装或未完整安装，继续执行 Step 1 开始完整安装流程。

> 校验逻辑：先检查 Step 2 目录与软链接是否存在；若存在则比对 `workspace-knowledge/git_version` 与目标版本号；再检查 openclaw.json 中是否已配置 knowledge-admin 与 qa-agent。详见 `scripts/check_installed.py`。

### Step 1: 收集参数

向用户确认以下两个角色名称（有默认值，用户可直接回车跳过）：

| 参数         | 说明               | 默认值     |
| ------------ | ------------------ | ---------- |
| `admin_name` | 知识管理员显示名称 | 客服管理员 |
| `qa_name`    | 客服助手显示名称   | 客服助手   |

### Step 2: 创建目录结构

```bash
mkdir -p /home/node/.openclaw/workspace-knowledge/workspace-qa/
mkdir -p /home/node/.openclaw/workspace-knowledge/knowledge/
```

在 workspace-qa 下创建指向上级 knowledge 的软链接：

```bash
cd /home/node/.openclaw/workspace-knowledge/workspace-qa/
ln -sf ../knowledge knowledge
```

### Step 3: 下载模板文件

```bash
cd /home/node/.openclaw/workspace-knowledge/
wget -O workspace-knowledge.zip https://oss-upload-temp.sophnet.com/workspace-knowledge_v{version}.zip
unzip -o workspace-knowledge.zip
rm -f workspace-knowledge.zip
```

### Step 4: 替换占位符

使用脚本替换 .md 文件中的 `{{客服助手}}` 和 `{{知识库管理员}}` 占位符。

先替换主工作空间目录（不含子文件夹）：

```bash
uv run {baseDir}/scripts/update_md.py \
  --dir /home/node/.openclaw/workspace-knowledge \
  --qa-name "{qa_name}" \
  --admin-name "{admin_name}"
```

再替换 workspace-qa 目录（不含子文件夹）：

```bash
uv run {baseDir}/scripts/update_md.py \
  --dir /home/node/.openclaw/workspace-knowledge/workspace-qa \
  --qa-name "{qa_name}" \
  --admin-name "{admin_name}"
```

> `{baseDir}` 为本 skill 所在目录，`{qa_name}` 和 `{admin_name}` 替换为 Step 1 收集的值。

### Step 5: 更新 openclaw.json

```bash
uv run {baseDir}/scripts/update_config.py \
  --admin-name "{admin_name}" \
  --qa-name "{qa_name}"
```

### Step 6: 完成提示

全部执行成功后，向用户展示以下信息。其中「客服子系统的API Secret」取 Step 5 中 `update_config.py` 输出里的「客服助手 API Secret」；若未保留该输出，可从 `openclaw.json` 的 `channels.bot-api.accounts["qa-agent"].apiSecret` 读取（与 `scripts/update_config.py` 中 `get_api_secret` 一致）。

```
✅ 您的智能客服系统已创建完成！

📂 知识库目录：/home/node/.openclaw/workspace-knowledge/knowledge
🤖 管理员会话：knowledge-admin
💁 客服助手会话：qa-agent
🔑 客服子系统的API Secret: <api_secret>

📌 快速上手：
1. 将知识库文档上传至 knowledge 目录
2. 切换到 knowledge-admin 会话，输入：处理一下 knowledge 里面的文档
3. 完成知识库初步创建后，即可通过 qa-agent 对外提供问答服务

📝 常用管理命令（在 knowledge-admin 会话中使用）：
  • 通过附件按钮上传文件，并输入：将文档加入知识库
  • 将 https://xxx 中的内容加入到知识库
  • 将 xxx 写入到知识库
  • 昨天客户都问了哪些问题
  • 昨天客户都有哪些反馈
  • 删除 xxx 知识库
```

## Error Handling

- **已安装检测**：Step 0 使用 `check_installed.py` 检测安装状态；`INSTALLED` 直接展示常用命令并结束，不执行 Step 1～6
- **可更新检测**：`UPDATABLE` 先提示用户有新版本并说明更新影响（不修改知识库、会重置 Agent 设置），等待用户明确确认后才执行 Step 2～6 完成更新；用户未确认则终止流程
- **目录已存在**：Step 2 使用 `mkdir -p`，已有目录不会报错
- **模板已下载**：Step 3 使用 `unzip -o` 覆盖已有文件
- **Agent 已存在**：Step 5 中 `update_config.py` 会检测重复并报错；若未执行 Step 0 而直接到 Step 5 报错，可提示用户「智能客服已安装」，并给出上述常用命令

## ⚠️ FORBIDDEN OPERATIONS

**Do NOT:**

- 修改 knowledge/ 目录下的知识库内容
- 直接编辑 openclaw.json（必须通过脚本）
- 跳过占位符替换步骤
- 检测到可更新时未经用户确认直接执行更新（必须等用户明确回复确认）
