btpanel_files

用途

宝塔面板文件管理技能（btpanel-files）用于对远程宝塔面板服务器进行文件与目录操作，提供浏览、读取、编辑、创建、删除、权限管理等基本文件操作能力。它是宝塔面板技能包中的文件管理技能，与 btpanel（运维监控）、btpanel-phpsite（PHP 网站管理）相互关联，并复用 btpanel 技能的配置系统。

主要能力

目录浏览：支持分页浏览大目录，显示文件/目录的名称、大小、权限、所有者、修改时间等信息，自动区分目录和文件，支持含空格和特殊字符的 URL 编码路径。
文件读取：支持大文件读取、指定显示最后 N 行（类似 tail）、返回文件编码、大小、只读状态等元信息，并自动检测文件编码。
文件编辑：支持直接指定内容、从本地文件读取内容、从标准输入读取内容三种方式；保存时通过 st_mtime 参数检查文件是否被修改，提供并发保护。
目录/文件管理：创建空目录、创建空文件、删除文件（移动到回收站）、删除目录（移动到回收站）。
权限管理：查看文件权限码与所有者，修改权限码、所有者、用户组，支持递归设置目录及子文件权限。

使用方式

该技能通过命令行脚本 {baseDir}/scripts/files.py 调用，需先配置服务器信息。

服务器配置复用 btpanel 技能的配置系统，使用 bt-config.py 管理：

# 查看帮助
python3 {baseDir}/scripts/bt-config.py -h

# 添加服务器
python3 {baseDir}/scripts/bt-config.py add -n prod-01 -H https://panel.example.com:8888 -t YOUR_TOKEN

# 列出服务器
python3 {baseDir}/scripts/bt-config.py list

# 删除服务器
python3 {baseDir}/scripts/bt-config.py remove prod-01

API Token 获取方法：登录宝塔面板，进入「面板设置」->「API 接口」，点击「获取 API Token」。

添加服务器时需确认 SSL 证书情况：若使用受信任证书（如 Let's Encrypt、商业 CA 证书）使用默认配置；若为自签名证书需添加 --verify-ssl false 参数。

常用命令示例：

# 列出目录内容
python3 {baseDir}/scripts/files.py ls /www

# 指定页码和每页数量
python3 {baseDir}/scripts/files.py ls /www/wwwlogs -p 2 -r 100

# 指定服务器
python3 {baseDir}/scripts/files.py ls /www --server prod-01

# 读取文件内容
python3 {baseDir}/scripts/files.py cat /www/test.txt

# 读取文件最后 N 行
python3 {baseDir}/scripts/files.py cat /www/logs/error.log -n 100

# 读取并显示详细信息
python3 {baseDir}/scripts/files.py cat /www/test.txt -v

# 编辑文件（直接指定内容）
python3 {baseDir}/scripts/files.py edit /www/test.txt "Hello World"

# 编辑文件（从本地文件读取内容）
python3 {baseDir}/scripts/files.py edit /www/test.txt -f ./content.txt

# 编辑文件（从标准输入读取）
cat ./content.txt | python3 {baseDir}/scripts/files.py edit /www/test.txt

# 创建目录
python3 {baseDir}/scripts/files.py mkdir /www/newdir

# 创建文件
python3 {baseDir}/scripts/files.py touch /www/test.txt

# 删除文件
python3 {baseDir}/scripts/files.py rm /www/test.txt

# 删除目录
python3 {baseDir}/scripts/files.py rmdir /www/olddir

# 查看权限
python3 {baseDir}/scripts/files.py stat /www/test.txt

# 修改权限
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt

# 修改权限并设置所有者
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt -u www -g www

# 递归修改目录权限
python3 {baseDir}/scripts/files.py chmod 755 /www/wwwroot -R

主要参数：全局参数 --server, -s 指定服务器名称（默认服务器）；ls 支持 path（默认 /www）、--page, -p（默认 1）、--rows, -r（默认 500）；cat 支持 path（必填）、--lines, -n（默认全部）、--verbose, -v；edit 支持 path（必填）、content（默认从 stdin 读取）、--file, -f、--encoding, -e（默认 utf-8）；chmod 支持 access（必填）、path（必填）、--user, -u、--group, -g、--recursive, -R。

适用场景

查看服务器目录文件列表，如查看 /www 目录或 Nginx 配置目录内容。
读取文件内容或查看日志最后若干行。
修改配置文件内容，并在保存前先读取确认修改范围。
创建新目录或空文件。
删除文件或目录（移动到回收站）。
查看或修改文件权限、所有者、用户组，包括递归设置目录权限。

限制与注意事项

版本要求：宝塔面板 >= 9.0.0，Python >= 3.10。
路径安全：所有路径参数会自动进行 URL 编码，支持含空格和特殊字符的路径。
删除操作：删除文件/目录会移动到回收站，非永久删除；如需永久删除需在宝塔面板中清空回收站。操作前仍需用户确认。
并发保护：保存文件时会自动检查文件是否被其他进程修改，如有冲突会提示。
权限要求：需要对目标路径有相应的读写权限，否则操作会失败。
敏感文件：部分系统文件可能因权限限制无法读取或修改。
文件大小限制：过大的文件可能导致读取/保存超时，建议分批处理。
文件下载 API：宝塔面板 /files?action=DownloadFile API 必须传递 filename 参数，否则返回 HTTP 500 错误；脚本已自动从 URL 提取文件名，无需手动指定。
AI 使用约束：操作前确认（修改文件前先读取内容）、执行前告知用户操作步骤、谨慎删除并确认目标路径、不主动读取敏感文件（如 /etc/shadow、.env、config.php 等含密码的文件）、修改重要配置文件前建议用户先备份。

常见问题

配置文件不存在：运行 python3 bt-config.py add 添加服务器配置。
PYTHONPATH 未设置：运行脚本前需设置 export PYTHONPATH=/path/to/btpanel-skills/src:$PYTHONPATH。
检查命令：python3 -c "from bt_common.bt_client import BtClient; print('✅ 模块正常')"；ls -la ~/.openclaw/bt-skills.yaml；python3 {baseDir}/scripts/monitor.py --server "你的服务器名"。

配置说明

配置文件位置：全局配置 ~/.openclaw/bt-skills.yaml，本地配置 config/servers.local.yaml，默认配置 config/servers.yaml。配置示例包含 servers 列表（name、host、token、disabled）以及 global 的 timeout 和 thresholds（cpu、memory、disk）。

响应格式

目录列表响应包含 dir、files、path、page 字段；文件内容响应包含 status、only_read、size、encoding、data、st_mtime；权限信息响应包含 chmod、chown。