feat: 文件管理器 + Windows兼容 + SVG主题适配 (v0.6.0)

新增: - services/web_panel/routes/files.py — 全功能文件管理后端API (11个端点) - pages/files.html + files.js — 文件管理前端 (浏览/编辑/上传/删除/右键菜单) - 插件Picker API: window.open+postMessage唤出文件选择器 - 符号链接目录双层面包屑 (逻辑路径+物理路径) - 文件系统全访问+跨平台 (Linux/Windows/macOS) - permission_rules.yaml新增4个filemanager.*权限修复: - SVG fill=currentColor 日夜模式自适应 - 特殊目录容错 (/dev/fd损坏符号链接/proc) - 面包屑每层级独立可点击+可编辑路径跳转 - ..行返回上级+data-is-dir补全 - rmlint→lstat回退损坏符号链接不炸页面文档: - 插件开发指南新增第八章(文件管理器集成) - 开发踩坑记录新增4条(特殊目录/双面包屑/SVG颜色/Windows) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-11 18:23:32 +08:00
parent 4a989bf50f
commit fd715eac2b
12 changed files with 1015 additions and 9 deletions
@@ -26,7 +26,8 @@
    - [7.2 开发中检查清单](#72-开发中检查清单)
    - [7.3 测试检查清单](#73-测试检查清单)
    - [7.4 发布检查清单](#74-发布检查清单)
-  - [八、总结](#八总结)
+  - [八、文件管理器集成 (v0.6.0)](#八文件管理器集成-v060-新增)
+  - [九、总结](#九总结)
    - [8.1 成功插件的特点](#81-成功插件的特点)
    - [8.2 持续改进](#82-持续改进)
    - [8.3 资源推荐](#83-资源推荐)
@@ -5036,9 +5037,85 @@ logger.error("错误信息", exc_info=True)
  - [ ] 测试升级流程
  - [ ] 确认卸载清理

-## 八、总结
+## 八、文件管理器集成 (v0.6.0 新增)

-### 8.1 成功插件的特点
+### 8.1 文件管理器 Picker API
+
+插件可通过 postMessage 接口调用文件管理器选择器，让用户在 WebUI 中快速选择目录或文件路径。无需插件自行实现文件浏览界面。
+
+#### 8.1.1 权限要求
+
+插件需要在 permissions.yaml 中声明文件管理相关权限：
+
+```yaml
+permissions:
+  - "filemanager.picker"     # 调用文件选择器
+  - "filemanager.access"     # 浏览/读取文件
+  - "filemanager.write"      # 写入/删除文件
+  - "filemanager.*"          # 完整权限
+```
+
+| 权限 | 级别 | 说明 |
+|------|------|------|
+| `filemanager.picker` | 基础 | 唤起文件选择器悬浮窗 |
+| `filemanager.access` | 读取 | 浏览目录、读取文件内容 |
+| `filemanager.write` | 写入 | 创建/删除/重命名/上传/写入 |
+| `filemanager.*` | 管理 | 完整文件管理访问 |
+
+#### 8.1.2 调用文件选择器
+
+插件 WebUI 页面通过 window.open 弹出选择器窗口：
+
+```javascript
+// 选择目录
+var picker = window.open(
+    '/SenSu/static/pages/files.html?picker=1&mode=dir',
+    'fm-picker', 'width=680,height=520'
+);
+
+// 选择文件
+var picker = window.open(
+    '/SenSu/static/pages/files.html?picker=1&mode=file',
+    'fm-picker', 'width=680,height=520'
+);
+
+// 监听选择结果
+window.addEventListener('message', function(e) {
+    try {
+        var data = JSON.parse(e.data);
+        if (data.action === 'fm-picked' && data.path) {
+            console.log('用户选择的路径:', data.path);
+            // 将路径发送到插件后端进行处理
+        }
+    } catch(ex) {}
+});
+```
+
+选择器关闭时通过 postMessage 返回: {"action":"fm-picked","path":"/选择的/路径"}
+
+#### 8.1.3 后端 REST API 参考
+
+插件后端可直接调用文件管理 API（需声明对应权限）：
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | /api/files/list?path=&show_hidden=0 | 列出目录内容 |
+| POST | /api/files/mkdir {path,name} | 创建目录 |
+| POST | /api/files/touch {path,name} | 创建空文件 |
+| GET | /api/files/read?path= | 读取文本(<=1MB) |
+| POST | /api/files/write {path,content} | 写入文本 |
+| POST | /api/files/delete {path} | 删除文件/目录 |
+| POST | /api/files/rename {path,new_name} | 重命名 |
+| POST | /api/files/upload (multipart) | 上传(<=50MB) |
+| GET | /api/files/download?path= | 下载文件 |
+| GET | /api/files/info?path= | 文件信息 |
+| GET | /api/files/picker?mode=file&path= | 选择器模式 |
+
+安全: 文件管理器可浏览整个文件系统，路径穿越攻击会被拦截。
+
+## 九、总结
+
+### 9.1 成功插件的特点

 1. **可靠性**：稳定运行，正确处理各种异常情况
 2. **易用性**：简洁的API，清晰的文档，直观的配置