\r \r

宝塔面板文件管理\r

\r 宝塔面板服务器文件操作工具，提供远程文件/目录浏览、读取、编辑、创建、删除、权限管理等基本文件操作能力。\r \r \r \r

图标资源\r

\r 技能包提供以下图标文件，可在生成报告时引用：\r \r | 文件 | 格式 | 用途 |\r |------|------|------|\r | icon/bt-logo.svg | SVG | 矢量图标，适合缩放 |\r \r

AI 使用约束\r

\r 本技能用于查询和修改服务器文件，AI 应遵循以下原则：\r \r

1. 操作前确认：修改文件前先读取文件内容，确认修改范围\r
2. 执行前告知：文件操作会影响服务器状态，AI 应先向用户简述即将执行的操作步骤\r
3. 谨慎删除：删除文件/目录前需告知用户，并确认目标路径\r
4. 隐私保护：不主动读取敏感文件（如 /etc/shadow、.env、config.php 等含密码的文件）\r
5. 备份建议：修改重要配置文件前，建议用户先备份\r \r 执行流程示例：\r

AI: 我将为您执行以下操作：\r
    1. 读取配置文件 /www/server/nginx/conf/nginx.conf\r
    2. 修改指定配置项\r
    3. 保存文件\r
    正在获取数据，请稍候...\r
    [执行命令]\r
    [展示结果和修改内容]\r
```\r
\r
## 宝塔面板相关技能矩阵\r
\r
当前宝塔面板技能包，共包含 3 个相互关联的技能：\r
\r
| 技能名称                | 描述 | 依赖关系                              |\r
|---------------------|------|-----------------------------------|\r
| **btpanel**         | 运维监控技能 | ✅ 基础技能，主要用于资源监控、网站状态检查、服务状态检查等    |\r
| **btpanel-files**   | 文件管理技能 | ✅ 提供远程服务器文件辅助服务，可以读取文件列表和内容       |\r
| **btpanel-phpsite** | PHP 网站管理技能 | ✅ 提供远程服务器 PHP 网站管理功能，能够部署和管理php网站 |\r
\r
\r
\r
### ⚠️ 常见问题\r
\r
**问题 1: 配置文件不存在**\r
```\r
错误：未找到配置文件\r
解决：运行 python3 bt-config.py add 添加服务器配置\r
```\r
\r
**问题 2: PYTHONPATH 未设置**\r
```bash\r
# 运行脚本前需要设置\r
export PYTHONPATH=/path/to/btpanel-skills/src:$PYTHONPATH\r
```\r
\r
### 检查命令\r
\r
```bash\r
# 检查 bt_common 模块\r
python3 -c "from bt_common.bt_client import BtClient; print('✅ 模块正常')"\r
\r
# 检查配置文件\r
ls -la ~/.openclaw/bt-skills.yaml\r
\r
# 测试连接\r
python3 {baseDir}/scripts/monitor.py --server "你的服务器名"\r
```\r
\r
---\r
\r
## 服务器配置管理\r
\r
> **重要:** 没有服务器信息时需要先添加\r
\r
本技能复用 `btpanel` 技能的配置系统，使用 `bt-config.py` 工具管理服务器：\r
\r
```bash\r
# 查看帮助\r
python3 {baseDir}/scripts/bt-config.py -h\r
\r
# 添加服务器\r
python3 {baseDir}/scripts/bt-config.py add -n prod-01 -H https://panel.example.com:8888 -t YOUR_TOKEN\r
\r
# 列出服务器\r
python3 {baseDir}/scripts/bt-config.py list\r
\r
# 删除服务器\r
python3 {baseDir}/scripts/bt-config.py remove prod-01\r
```\r
\r
**获取 API Token 的方法**：\r
1. 登录宝塔面板\r
2. 进入「面板设置」->「API 接口」\r
3. 点击「获取 API Token」\r
\r
**重要提示 - SSL 证书验证配置**：\r
添加服务器时，AI 应询问用户：\r
> "您的宝塔面板是否使用了受信任的 SSL 证书（如 Let's Encrypt、商业 CA 证书）？"\r
\r
- ✅ **是**（受信任证书）→ 使用默认配置，无需额外参数\r
- ⚠️ **否**（自签名证书）→ 添加 `--verify-ssl false` 参数\r
\r
**示例**：\r
```bash\r
# 自签名证书场景\r
python3 {baseDir}/scripts/bt-config.py add -n prod-01 -H https://panel.example.com:8888 -t YOUR_TOKEN --verify-ssl false\r
\r
# 受信任证书场景（默认）\r
python3 {baseDir}/scripts/bt-config.py add -n prod-01 -H https://panel.example.com:8888 -t YOUR_TOKEN\r
```\r
\r
## 常用场景\r
\r
### 场景一：查看目录文件列表\r
\r
当用户需要查看服务器某个目录的内容时：\r
\r
```bash\r
# 查看/www 目录\r
python3 {baseDir}/scripts/files.py ls /www\r
\r
# 查看指定目录\r
python3 {baseDir}/scripts/files.py ls /www/server/nginx/conf\r
\r
# 带分页查看\r
python3 {baseDir}/scripts/files.py ls /www/wwwlogs -p 2 -r 100\r
```\r
\r
**用户意图识别**：\r
- "看看/www 目录下有什么" → 执行 `files.py ls /www`\r
- "查看 Nginx 配置文件目录" → 执行 `files.py ls /www/server/nginx/conf`\r
- "这个目录有哪些文件" → 执行 `files.py ls 路径`\r
\r
### 场景二：读取文件内容\r
\r
当用户需要查看文件内容时：\r
\r
```bash\r
# 读取文件\r
python3 {baseDir}/scripts/files.py cat /www/test.txt\r
\r
# 读取文件最后 50 行\r
python3 {baseDir}/scripts/files.py cat /www/logs/error.log -n 50\r
\r
# 读取并显示文件信息\r
python3 {baseDir}/scripts/files.py cat /www/server/nginx/conf/nginx.conf -v\r
```\r
\r
**用户意图识别**：\r
- "帮我看看这个文件内容" → 执行 `files.py cat 路径`\r
- "查看日志最后几行" → 执行 `files.py cat 路径 -n 50`\r
- "这个文件是什么编码" → 执行 `files.py cat 路径 -v`\r
\r
### 场景三：编辑文件内容\r
\r
当用户需要修改文件内容时：\r
\r
```bash\r
# 直接修改文件内容\r
python3 {baseDir}/scripts/files.py edit /www/test.txt "新内容"\r
\r
# 从本地文件读取内容并保存\r
python3 {baseDir}/scripts/files.py edit /www/test.txt -f ./local-file.txt\r
```\r
\r
**用户意图识别**：\r
- "修改这个文件，加上 XXX" → 先读取文件，再执行 `files.py edit`\r
- "更新配置文件" → 先读取文件，确认后执行 `files.py edit`\r
\r
**重要**：编辑文件前必须先读取原内容，确认修改范围后再保存。\r
\r
### 场景四：创建目录/文件\r
\r
当用户需要创建新目录或文件时：\r
\r
```bash\r
# 创建目录\r
python3 {baseDir}/scripts/files.py mkdir /www/newdir\r
\r
# 创建文件\r
python3 {baseDir}/scripts/files.py touch /www/test.txt\r
```\r
\r
**用户意图识别**：\r
- "新建一个目录" → 执行 `files.py mkdir 路径`\r
- "创建一个空文件" → 执行 `files.py touch 路径`\r
\r
### 场景五：删除文件/目录\r
\r
当用户需要删除文件或目录时：\r
\r
```bash\r
# 删除文件\r
python3 {baseDir}/scripts/files.py rm /www/test.txt\r
\r
# 删除目录\r
python3 {baseDir}/scripts/files.py rmdir /www/olddir\r
```\r
\r
**用户意图识别**：\r
- "删除这个文件" → 确认路径后执行 `files.py rm 路径`\r
- "清理这个目录" → 确认路径后执行 `files.py rmdir 路径`\r
\r
**重要**：删除操作会将文件/目录移动到回收站，非永久删除。但操作前仍需用户确认。\r
\r
### 场景六：查看/修改文件权限\r
\r
当用户需要管理文件权限时：\r
\r
```bash\r
# 查看文件权限\r
python3 {baseDir}/scripts/files.py stat /www/test.txt\r
\r
# 修改文件权限\r
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt\r
\r
# 修改权限并设置所有者\r
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt -u www -g www\r
\r
# 递归修改目录权限\r
python3 {baseDir}/scripts/files.py chmod 755 /www/wwwroot -R\r
```\r
\r
**用户意图识别**：\r
- "查看这个文件的权限" → 执行 `files.py stat 路径`\r
- "修改文件权限为 755" → 执行 `files.py chmod 755 路径`\r
- "把这个目录权限改对" → 确认正确权限后执行 `files.py chmod`\r
\r
## 版本要求\r
\r
- **宝塔面板**: >= 9.0.0\r
- **Python**: >= 3.10\r
\r
## 用法\r
\r
### 查看目录列表\r
\r
```bash\r
# 查看帮助\r
python3 {baseDir}/scripts/files.py -h\r
\r
# 列出目录内容\r
python3 {baseDir}/scripts/files.py ls /www\r
\r
# 指定页码和每页数量\r
python3 {baseDir}/scripts/files.py ls /www/wwwlogs -p 2 -r 100\r
\r
# 指定服务器\r
python3 {baseDir}/scripts/files.py ls /www --server prod-01\r
```\r
\r
### 读取文件\r
\r
```bash\r
# 读取文件内容\r
python3 {baseDir}/scripts/files.py cat /www/test.txt\r
\r
# 读取文件最后 N 行\r
python3 {baseDir}/scripts/files.py cat /www/logs/error.log -n 100\r
\r
# 读取并显示详细信息\r
python3 {baseDir}/scripts/files.py cat /www/test.txt -v\r
```\r
\r
### 编辑文件\r
\r
```bash\r
# 直接指定内容\r
python3 {baseDir}/scripts/files.py edit /www/test.txt "Hello World"\r
\r
# 从本地文件读取内容\r
python3 {baseDir}/scripts/files.py edit /www/test.txt -f ./content.txt\r
\r
# 从标准输入读取\r
cat ./content.txt | python3 {baseDir}/scripts/files.py edit /www/test.txt\r
```\r
\r
### 创建目录/文件\r
\r
```bash\r
# 创建目录\r
python3 {baseDir}/scripts/files.py mkdir /www/newdir\r
\r
# 创建文件\r
python3 {baseDir}/scripts/files.py touch /www/test.txt\r
```\r
\r
### 删除文件/目录\r
\r
```bash\r
# 删除文件\r
python3 {baseDir}/scripts/files.py rm /www/test.txt\r
\r
# 删除目录\r
python3 {baseDir}/scripts/files.py rmdir /www/olddir\r
```\r
\r
### 查看/修改权限\r
\r
```bash\r
# 查看权限\r
python3 {baseDir}/scripts/files.py stat /www/test.txt\r
\r
# 修改权限\r
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt\r
\r
# 修改权限并设置所有者\r
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt -u www -g www\r
\r
# 递归修改目录权限\r
python3 {baseDir}/scripts/files.py chmod 755 /www/wwwroot -R\r
```\r
\r
## 参数说明\r
\r
### 全局参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `--server`, `-s` | 指定服务器名称 | 默认服务器 |\r
\r
### ls 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 目录路径 | /www |\r
| `--page`, `-p` | 页码 | 1 |\r
| `--rows`, `-r` | 每页显示数量 | 500 |\r
\r
### cat 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 文件路径 | 必填 |\r
| `--lines`, `-n` | 显示最后 N 行 | 全部 |\r
| `--verbose`, `-v` | 显示文件信息 | 否 |\r
\r
### edit 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 文件路径 | 必填 |\r
| `content` | 文件内容 | 从 stdin 读取 |\r
| `--file`, `-f` | 从本地文件读取内容 | 无 |\r
| `--encoding`, `-e` | 文件编码 | utf-8 |\r
\r
### mkdir 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 目录路径 | 必填 |\r
\r
### touch 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 文件路径 | 必填 |\r
\r
### rm 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 文件路径 | 必填 |\r
\r
### rmdir 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 目录路径 | 必填 |\r
\r
### stat 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `path` | 文件路径 | 必填 |\r
\r
### chmod 命令参数\r
\r
| 参数 | 说明 | 默认值 |\r
|------|------|--------|\r
| `access` | 权限码（如 755, 644） | 必填 |\r
| `path` | 文件路径 | 必填 |\r
| `--user`, `-u` | 所有者用户名 | 当前用户 |\r
| `--group`, `-g` | 用户组名 | 当前组 |\r
| `--recursive`, `-R` | 递归设置子目录和文件 | 否 |\r
\r
## 功能特性说明\r
\r
### 目录浏览\r
\r
- 支持分页浏览大目录\r
- 显示文件/目录的详细信息（名称、大小、权限、所有者、修改时间）\r
- 自动区分目录和文件\r
- 支持 URL 编码路径（自动处理含空格和特殊字符的路径）\r
\r
### 文件读取\r
\r
- 支持大文件读取\r
- 支持指定显示行数（类似 `tail` 命令）\r
- 返回文件编码、大小、只读状态等元信息\r
- 自动检测文件编码\r
\r
### 文件编辑\r
\r
- 支持直接指定内容保存\r
- 支持从本地文件读取内容\r
- 支持从标准输入读取内容\r
- 并发保护：保存时检查文件是否被修改（通过 `st_mtime` 参数）\r
\r
### 目录/文件管理\r
\r
- 创建空目录\r
- 创建空文件\r
- 删除文件（移动到回收站）\r
- 删除目录（移动到回收站）\r
\r
### 权限管理\r
\r
- 查看文件权限（权限码、所有者）\r
- 修改文件权限码\r
- 修改文件所有者\r
- 修改文件用户组\r
- 递归设置目录及子文件权限\r
\r
## 注意事项\r
\r
1. **路径安全**：所有路径参数会自动进行 URL 编码，支持含空格和特殊字符的路径\r
\r
2. **删除操作**：删除文件/目录会移动到回收站，非永久删除。如需永久删除需在宝塔面板中清空回收站\r
\r
3. **并发保护**：保存文件时会自动检查文件是否被其他进程修改，如有冲突会提示\r
\r
4. **权限要求**：需要对目标路径有相应的读写权限，否则操作会失败\r
\r
5. **敏感文件**：部分系统文件可能因权限限制无法读取或修改\r
\r
6. **文件大小限制**：过大的文件可能导致读取/保存超时，建议分批处理\r
\r
7. **文件下载 API**：宝塔面板 `/files?action=DownloadFile` API 必须传递 `filename` 参数，否则返回 HTTP 500 错误。脚本已自动从 URL 提取文件名，无需手动指定\r
\r
## 响应格式\r
\r
### 目录列表响应\r
\r
```json\r
{\r
  "dir": [\r
    {"nm": "目录名", "sz": "大小", "mt": "时间戳", "acc": "权限", "user": "所有者"}\r
  ],\r
  "files": [\r
    {"nm": "文件名", "sz": "大小", "mt": "时间戳", "acc": "权限", "user": "所有者", "rmk": "备注"}\r
  ],\r
  "path": "/www",\r
  "page": "页码信息"\r
}\r
```\r
\r
### 文件内容响应\r
\r
```json\r
{\r
  "status": true,\r
  "only_read": false,\r
  "size": 639,\r
  "encoding": "utf-8",\r
  "data": "文件内容",\r
  "st_mtime": "1753161154"\r
}\r
```\r
\r
### 权限信息响应\r
\r
```json\r
{\r
  "chmod": "755",\r
  "chown": "www:www"\r
}\r
```\r
\r
## 配置说明\r
\r
技能包复用 `btpanel` 技能的配置系统，配置文件位置：\r
\r
- 全局配置：`~/.openclaw/bt-skills.yaml`\r
- 本地配置：`config/servers.local.yaml`\r
- 默认配置：`config/servers.yaml`\r
\r
**配置示例**：\r
\r
```yaml\r
servers:\r
  - name: prod-01\r
    host: https://panel.example.com:8888\r
    token: YOUR_API_TOKEN\r
    disabled: false\r
\r
global:\r
  timeout: 30\r
  thresholds:\r
    cpu: 80\r
    memory: 85\r
    disk: 90\r
```\r